DW4H (Documentation – why, when, what, who, how)
I was asked recently to explain how the development process deals with documentation.
The question that needs to be answered is "Why?" — why is documentation needed, by whom, for what purpose? In my view, there are two purposes for documentation, and they are radically different from each other.
The first purpose is to describe what is going to be done in the future. This future-facing documentation — in the form of traditional project mission, value forecasts, customer requirements, technical architecture and design specifications — is produced before a product is built. It defines the work that will be done.
The second purpose is to describe what has been done in the past. This historical documentation — usually the updated design and implementation documents — is produced as the product is being built, or after the product has been built and deployed. It defines the work that was actually done.
As you see, the timing of the documentation strongly influences what is produced, when it is produced, who produces it and how it is used. It also influences the value of the documentation.
Future-facing documents generally form constraints on the planned work. The intent is to focus the effort on the desired outcome. Because it is future-facing, it is necessarily uncertain and subject to change as the future comes closer.
Because the future is uncertain, future-facing documentation should be expressed with the same degree of uncertainty. As we plan a project, we can be highly certain about some subjects — project mission, customer goals, architectural principles and system models — and far less certain about other subjects — value forecasts, customer requirements, functional capabilities, technical architecture, design specifications. The future-facing documentation should reflect that.
Likewise, future-facing documentation must be easily changed, as the effort progresses and we become smarter and more certain about what we are building and how we are building it. Documentation should always be current (to avoid confusion) and never be a burden. Burdensome documentation becomes obsolete. Obsolete documentation becomes ignored.
Historical documents generally form descriptions of the executed work. The intent is to help some unknown future persons who may need to know how the products were designed, how they were built, and how they behave. Because it is historical, it can be as certain and free from change as past events and real products are. (This doesn’t keep them from being incomplete or wrong, of course.)
Historical documents should be expressed with a high degree of certainty. All the uncertainty that we faced at the start of the project should be removed at the end of the project. Historical documents describe the customer requirements that were actually met, the technology that was actually deployed, the design that was actually implemented, and the capabilities that are actually supported. While historical documents are still subject to change, the change is typically less frequent and less urgent than it is with future-facing documents.
With these thoughts in mind, what documentation should be produced as future-facing and what should be historical?
The key distinguishing characteristic is the degree of certainty that we can apply to each. When preparing future-facing documents, we should include what we are certain about and minimize what is uncertain. To that end, these are the future-facing documents that should be prepared — notice the use of the future tense in the examples:
- Project Mission: a general statement of what the purpose and value of the project is. For example: "The Argyle project will provide a self-service facility to agents seeking to activate new customers, improving our responsiveness to agent needs."
- Customer Goals: more specific statements of project value, based on the expectations that have been set and the business rationale for undertaking the project: For example: "The Argyle project will provide ready-to-reference customer records in 4 hours or less." "The Argyle project will reduce IT involvement in the activation of new customer." "The Argyle project will comply with data asset protection policies."
- Architectural Principles: guiding statements for the things being built, governing overall behavior, maintainability, security, flexibility, resilience, and other (typically, non-functional) attributes. For example: "Argyle will incorporate standard, open interface technology between encapsulated functions." "Argyle will adhere to the XYZ application stack model." "Argyle will anticipate changes to the core security framework."
- System Models: guidelines describing how different parts of the system will interact, using Use Cases, Scenarios, User Stories, Collaboration Diagrams, Data Model, Database Model and similar modeling techniques. For example: "The User can create a new customer record." "The User can authorize another User to access the new customer record." "The System can prevent a new customer from exceeding its defined credit limit." "The System can give priority to one customer over another." "The System can replicate non-identifying data from a customer record."
The Use Cases are expressed in term of what functionality is being delivered to the User and what activities are being taken to realize that functionality. The "Main Success Scenario" tells the developer what needs to be done; the "Pre-Conditions" section tells the developer what he/she can expect is already done before this code is invoked — it is the responsibility of the invoking code to verify that the pre-conditions are met.
Where a data model is required, an understanding of the affected portion of the data model and database are included in the System Models documentation. The data model should be limited only to that portion of the data model that is actually affected by the Use Case or by the project outcome. This is to keep the team’s focus on the limited scope of the project and to avoid distractions into non-productive areas. Ideally, the data access model (describing how to interact with the database) will have preceded the project; in that case, the data access model is needed, not the database model.
In the Scrum process for software development (coupled with Extreme Programming practices), Use Cases are sufficient to drive and measure team activity and progress. The team makes progress by realizing a Use Case. The Use Case is not a design specification; the team is responsible for identifying and satisfying the implementation details. The team is also responsible for ensuring that those details work together with the other Use Case details to form a cohesive and coherent structure, usually under the guidance of an architect and lead designers and with the concurrence of the Product Owner. Because there is constant communication and visibility within a Scrum team, implementation details and choices are exposed and assessed continuously within the team.
With this continuous exchange underway, the four future-facing documents are sufficient to move the project forward.
Historical documents are completed as the project moves forward. These can be made an essential part of the deliverables; if the historical documentation is not completed, the deliverable is not completed. (Remember that, in Scrum, a deliverable is either Done or Not Done — there is no middle ground.)
Since the purpose of historical documents is to guide those who will come in the future, the historical documents must be accurate and complete. They must contain sufficient detail that the future developer will be able to understand and properly modify what has been built without placing the product at risk.
These historical documents satisfy this purpose:
- Annotated Code: The core software documentation is the code. Annotating the code is the primary documentation practice. A reader should be able to follow the processing logic and understand the purpose of the code in detail.
- Detailed Design Description: Normally, these would have been called "design specifications". However, since they come at the end of development and are historical, they are more properly named "design descriptions". The design description includes object descriptions (name, purpose, properties, methods), collaborations, failure detection and treatment, data manipulation (retrieval and modification), and references to code sections where warranted. A reader should be able to understand the cross-dependencies and interrelationships between each component of the system, and thereby be able to perform an "impact analysis" for any suggested changes.
- Test Descriptions and Results: This must include each repeatable test scenario, including (examples of) the actual test input and output and the test environment. A reader should be able to reproduce the test results.
- Exception Reports: If there have been any variations from the team’s common practice, these must be explicitly called out in an Exception Report. The Exception Report must include a rationale for the variation, a description of the effect if the variation were not taken, and, if possible, suggested alternative practices that might be applied. The Exception Reports should be infrequent, even rare. However, when Exceptions exist, the Exception Reports are crucial to avoiding invalid assumptions in the future. A reader should be able to easily identify non-standard or unexpected implementations.
These sets of documentation provide all the guidance required for a successful software development effort, without undue burden on the project. They offer a set of documentation that can be relied upon to be current and accurate. They address the needs of the audience without constraining the team when new discoveries are made. They address with certainty the things we are certain about, and make broad "guiding" statements about things that are uncertain.
With this approach to documentation, the team can move forward with agility and not be hamstrung by our unavoidable ignorance about the future.