While it is true that agile projects often produce less documentation, some documentation is still useful in order to communicate project scope, progress, and ideas. However, teams are asked to embrace some additional realities:
- We rarely know everything up front and that producing high quality documentation about requirements or design that may not be implemented is wasteful.
- A document isn’t the only vehicle for expressing or transferring good thinking and ideas
1. Is this document for internal team use only? (example, for hand-off from one person to another) If so…
Can you communicate the information through a conversation instead?
Can you communicate the information through code instead?
Can you communicate through a drawing, picture, or other lite weight model instead?
If the answer is no to the questions above, what is the minimum amount of information you can capture in the document that would serve as a reminder for a future conversation?
2. Is the document for now or later?
If the document is required now, consider simplifying or replacing with a conversation, white board pictures, paper prototypes, code snippets, or brief videos summarizing decisions. If the document is for later (ex. Help Documents, regulatory documents, etc), then consider creating it later or adding it to your done criteria for each item in your backlog. Documents for ‘later’ do not need to be created up front but can be continually updated throughout the project. If the document is for later, how often do people actually use it?
3. Who is the audience for this documentation?
Ask your audience about the minimum set of information they require.
4. What is the business value of this documentation?
If it has little value, then it doesn’t need a lot of information. If it has a lot of value (like a required regulatory document), then make sure the level of detail accomplishes the required value and no more. Why are we producing this document? Would you pay someone to create this document? Is it worth the investment?
5. Is this information available through another means?
Instead of creating API documentation or SOA documentation, consider using one of the many tools available to generate your documentation. Instead of asking someone to read a design document, ask them to read and run your tests.
6. Does this document specify requirements or design in detail?
Since requirements change on our projects, capturing this level of detail up front may not be providing value to the project.
7. How often have I had to change this document in the past?
This is often a clue that your document contains too much detail.
8. Can I specify this information through an automated test instead?
Specification by Example (also known as ATDD or BDD) promotes writing your requirements as automated test cases (examples) instead of requirements bullets. This allows you to have an executable yet readable specification that is developed throughout the project in cooperation with your client and the development team. Test Driven Development is a technical practice that developers can use to write unit tests that describe and validate their code and design. This practice has lots of advantages, but one of the side effects is that the unit tests specify how and why the code works so that future developers viewing this code can understand this information without having to rely on out of date documentation.
9. How should I create the content for this document?
Consider creating the content using inclusive models. Inclusive models allow others to easily contribute as active participants in creating the content of the document and often involve paper, post-its, and whiteboards. A 35 page word document draft is not an inclusive model - you are more likely to get grammar and formatting edits than suggestions for improving or even re-doing the content.
10. Is this document so big that no one will read it?
“An attempt to avoid this ambiguity by writing everything down often leads to a document of the type Winston Churchill was working on before he was Prime Minister. Mr. Churchill described it as follows: ‘this document, by its very size, ensures that it will never be read.’”- Allan Shalloway in “The Role of Quality Assurance in Lean-Agile”
For additional reading on this topic, take a look at the following links:
No comments:
Post a Comment