6
Agile Documentation?
This chapter focuses on the documentation requirements or lack thereof on agile projects. The question mark behind the chapter’s title is not a discrepancy. It represents the question that is addressed throughout this discussion. As an overview of what is to come throughout this chapter, the answer will not be “Yes” or “No” but more of a “How much?” We recall the agile value: “Working software over comprehensive documentation.” Agile methods value working software more than comprehensive documentation, however, this does not necessarily mean there is no value in capturing information in written form on the project.
AGILE DOCUMENTATION BEST PRACTICES
Some agile experts believe that documentation actually increases project risk.* They feel that if documentation must be developed, the motive should be for efficiency purposes only. Agile project documentation should only be developed, according to some experts, for the attainment of specific goals. We begin our discussion with an overview of agile documentation best practices.
Selecting What to Document
Documentation requirements on a traditional project require that specifications be documented (i.e., requirements or design specs). In contrast, the agile project uses what are referred to as specifications in executable forms such as, for example, a test created for a test-driven development (TDD) scenario. TDD is a software-based technique that requires tests to be written prior to the creation of the code. A TDD cycle has several steps as shown in Figure 6.1. Code created during this activity is considered to be a dynamic specification used to validate a user story’s functionality. This agile documentation concept is referred to as “single source information.” It won’t be necessary to create static documentation in a case like this because TDD is very dynamic in nature. In addition, the preference is always to use an executable specification rather than a written one.
FIGURE 6.1
The test-driven development process.
Stable Information
Documentation should be delayed until the latest possible time on the agile project. This is referred to as “document late,” an agile documentation best practice. In the case of critical material, the recommendation is to take notes for later use. Formal documentation should be developed toward the project’s end. Hypothetical information should not be selected for documentation. With regard to system documentation, it would be ideal to use built-in software tools to generate this type of information.
Simple Documentation
Agile experts believe that comprehensive documentation is not a method that guarantees a successful project and that too much documentation on the agile project can contribute to project failure. When documentation is created, it should be concise and simple. Short documents are considered to be more trustworthy than those that are longer. Why would this be the case? We would not expect the shorter document to contain information in detail, however, it would be relatively easy to use short documents as a map to point us to other documents that contain more information. There is more trust in a short document because we can easily determine its level of accuracy as opposed to a large document that has the potential to have a larger number of errors. Lastly, information should never be repeated in multiple places and it is acceptable to use references rather than the actual information within agile documentation.
Minimal Document Overlap
Information should be in one place only and overlapping should not occur. In the event that an overlap does occur, it should be very minimal. Documents should be just good enough to satisfy a project goal. One-page topics is a good practice and using small documents as the foundation to create larger ones is recommended.
Proper Place for Documents
The proper place for documentation should always be based on the needs of the customer and the customer’s choice of location. According to the Quality Work Principle,* information should be recorded in the place where it will enhance the work. This principle states that: “Nobody likes sloppy work. The people doing the work don’t like it because it’s something they can’t be proud of, the people coming along later to refactor the work (for whatever reason) don’t like it because it’s harder to understand and to update, and the end users won’t like the work because it’s likely fragile and/or doesn’t meet their expectations.”
Publicly Displayed Information
When information is displayed publicly by means of a whiteboard or a website, this is referred to as using an information radiator. The better the communication is on the project, the less the project will need extensive documentation. This is the reason why people and their interactions are valued more than comprehensive documentation. Agile methods believe that face to face is a more effective way to communicate in comparison with lengthy documentation. Figure 6.2 shows the effectiveness of several types of communications channels from the agile perspective.
Create Documentation with a Purpose
Documentation should only be developed in situations where an objective needs to be reached for the project as a whole. This requisite should be clear, essential, and immediate. In contrast to traditional project management, agile methods never dictate the adherence to a repeatable process that uses templates. In order to be effective, there should never be an expectation that one size will fit all when it comes to agile documentation. Agile methods are adaptive based on the needs of the project and most documentation should never be created unless requested by a stakeholder.
Focus on Customer Needs
It is best to communicate with the document’s audience so that an understanding of the requirements is established. This would mean that the customer who requested the documentation would need to be involved. Negotiations with the customer may need to take place so that only the minimum requirements can be provided. Questions that need to be asked might be the following:
FIGURE 6.2
Methods of communications. (Derived from Ambler, S. (2012). Agile Modeling: Best Practices for Agile/Lean Documentation. Retrieved from http://www.agilemodeling.com/essays/agileDocumentationBestPractices.htm. With permission.)
What does this customer do?
How does this customer do what they do?
How does this customer want to use the documentation that is being requested?
This would be considered an exercise in determining the needs of the customer and providing what is needed and nothing more.
Let the Customer Determine Document Value
The agile project must always deliver value to the customer and providing documentation is no exception to this rule. The author of any customer documentation must provide value and it would then be the customer’s responsibility to verify that the value provided is of an acceptable level. In addition to value added, it must also be determined that the document has real meaning.
Iterative Documentation
Just as the product is delivered iteratively, documentation should be delivered in this manner as well. The recommended way to create documentation is to write a draft, gain feedback, and then update the document based on the feedback that has been provided. The iterative approach ensures that the intended audience provides the necessary feedback so that their needs are satisfied. Feedback also provides information from the stakeholder as to the amount of value added.
Better Ways to Communicate
We previously mentioned Figure 6.2 (Methods of Communication) as showing that paper-based communication has the lowest ranking for effectiveness. A major problem with communications is the understanding of the information presented and not necessarily the actual documentation. The project’s goal is not to bury or overburden users with documentation, but to ensure that the developed product has high value and performs as intended. Documentation does have its usefulness in terms of improving the transfer of knowledge. Face-to-face conversations have the highest level of effectiveness on the agile project. Documentation is good for situations where there is distance between team members. Recall that the agile team is colocated so there is very little need for documentation as a result of this physical configuration.
Current Documents
Update-to-date modeling documents are more valuable than those that have not been kept current. It is a positive indication when these documents are current because it is certain that value has been added. These types of documents should be used as starting points when developing new material.
When to Update Documents
Model diagrams (design, interface, etc.) should only be updated when it is absolutely necessary. This means that updates should only take place when there is pain associated with not having the model updated, or in other words, there is a negative impact. The logic behind this method is based on the fact that code does in fact change frequently, however, models should only be good enough, and very little time should be spent updating documentation. If the model is good enough, then that would be acceptable because agile methods don’t require perfection in documentation. Just good enough is enough.
Documentation Requirements
Agile methods view documentation requests as requirements. This means that documentation requests should be estimated, given a priority, and treated as a task. When treating documentation as a requirement, the customer should consider this action as a business decision. Documents should only be developed as a result of a stakeholder’s request.
Require Justification for Documentation
Prior to creating documents, a best practice is to make sure that the requester fully understands what is being asked. It is a good idea to gain an understanding of why the document is needed. The requester must also be made aware that documentation is not “free” and that there will be associated costs involved. Often when questions are asked, it is revealed that the need for the document is not genuine. There must be a benefit in developing the document that must be larger than the cost of creation and maintenance. The need for the documentation should exist rather than just the desire to have it. A stakeholder must make the decision to invest in the creation of the document. In addition, the documentation must be created to provide the best value and the request should never be taken lightly.
Required Documentation
There is some documentation that may be actually required. In this case, the requirements are to “minimally” develop only what is absolutely necessary. On occasion, user manuals, product support, or operations documentation may be required. It is important to remember that the main focus of the project is to develop and deliver the software product. Making sure that the product can be maintained, supported, and operated is important as well. In most cases, only high-level information should be documented and details should be kept at a minimum.
Writing Experience Required
When feasible, a technical writer should be utilized to create project documentation. These individuals have experience in organizing and presenting information. In the event that a writing professional is not an option, the ownership of a document can be shared so that several people can contribute. Other options include dictation software that generates the words as they are spoken, enrolling in a technical writing course, and writing with a partner, which is referred to as “pair documenting.”
CHAPTER SUMMARY
We now provide a summary of the important concepts covered on agile documentation.
• Agile documents should be kept simple.
• Agile documents should be “just good enough.”
• Agile document requests should require justification.
• Documents should be updated only when necessary or when there will be “pain” if not updated.
• Most documentation should only be done when requested by a stakeholder and justified.
• Documentation is the least effective way to communicate on the agile project.
• Document creation should be done iteratively.
• Documents should have minimal overlap.
• Documentation should always add value.
• Working software is valued more than documentation.