Kent McDonald shares some tips on documentation approaches that he and his team used on a recent project. The key is to find the bare minimum of documentation that you need from both a project documentation and system documentation perspective and only add additional documentation when it hurts not to add it.
A delivery team I worked with recently was trying to figure out its documentation approach. The team members were working on an established system core to the operations of the organization. Their current documentation was a set of nearly 100 requirements specifications each focused on a specific module and totaling over a hundred pages. These specifications consisted primarily of text statements with the occasional interface prototype. When a change was needed, analysts on the team would pick the appropriate specs, mark them up to reflect the changes that were needed, and then provide them to the developers and testers on the team. Inevitably, the changes that actually happened were different than what had been marked up in the specs, so the analysts went back and updated the specs—most of the time.
Everyone realized that this was not an ideal solution, so they wanted to come up with a better approach. They were looking for a solution that clearly communicated what needed to change, provided a good record of the system as built for future uses, and did so in as efficient and effective manner possible.
The key is realizing that there are two primary kinds of documentation, one of which covers the things that the customer asks for and the other accounting for what the team members need to do their job. The documentation that teams need to do their job can be split into two types: project documentation and system documentation.
Project Documentation
The delivery team needs to communicate the changes necessary for a given project. This information is best organized based on the changes. The extent of the documentation is based on how well the team communicates via other means and the approach the team uses. My preference is for extremely light project documentation that includes the following
- Features and user stories: These are ways to keep track of the various things that the delivery team is trying to help their stakeholders accomplish, effectively a way to organize the various changes that the delivery team is looking to produce.
- Examples: -structured information in the form of Given—When—Then scenarios or decision tables that describe system behavior and the rules that are expected to be enforced when a user story is delivered
- Models: Wire frames, data models, or process flows further describe the stories. Often the models are general in nature such that they help describe several stories, but sometimes they can be created specifically for a given story.
- Acceptance Criteria: This acts as further description of the stories that weren’t covered by the examples or models.
Project documentation is temporary in nature since it is used to describe the specific changes that are needed in the effort and hence depend on a specific current and future state. User stories may be used as a source of release notes, and the examples, models, and acceptance criteria may provide a source for system documentation, but does not entail the system documentation itself.
System Documentation
Delivery teams need to understand the current state of the system so they know where to start. While the system itself and tests written against it should provide most of this information, there will always be a need for additional sources of information, especially for aspects that are not readily apparent, such as rules, permissions, metadata, and process flows. This information is best organized in the context of the system, not necessarily by what changes were made when.
This information can take many forms, but I usually like to have some combination of the following:
- Glossary: Provides definitions for the commonly used terms in the domain in which the system operates.
- Business Rule Catalog: Describes what the rules are without indicating how they are enforced, which is typically noted in one of the other artifacts or is represented by tests.
- Metadata: Data about the data that the system collects, stores, and provides.
- Process flows: Describes the business processes that the system supports.
- User Interfaces: While I usually prefer systems to be “self documenting” when it comes to user interfaces, if there are a lot of operations going behind the scenes or the enforcement of business rules is not inherently obvious, these come in handy to reference where the business rules are enforced and how a user flows through the system.
- Permissions: A description of what roles can perform what functions in the system.
Use cases are also used in conjunction with or instead of process flows depending on the preferences of the organization.
System documentation focuses on the as-built system and acts as a reference for future efforts. It is organized based on system functionality, rather than based on when changes were made to the system, making it easier for people maintaining the information they need quickly.
Product and System Documentation, an Example
The team I mentioned in the opening to this article chose to replace the requirements specifications with a set of system documentation that consisted of use cases that described the main goals that users had for using the system. These use cases then referenced a business-rules catalog, a messaging catalog, a data dictionary, and a glossary. As much as possible the team members placed information in only one place so that the maintenance burden was minimized.
When they needed to make a change, they identified the necessary changes through user stories that they further described through the use of acceptance criteria, examples, and hand-drawn screen mockups where appropriate. Then, to make sure the system documentation reflected the as-built system, they included updating the system documentation in their definition of done.
They found this approach more useful than their previous approach because the documentation they used to communicate changes during the project was light-weight and suited for that purpose, while the documentation they used as a reference in between projects was much more suited for that purpose.
The only disadvantage to this approach was the large effort it took to initially establish the new system documentation. They however found enough value in the new organization that they were willing to put forth the effort to match this switch. I don’t know that this effort makes sense in all cases; if working with another team in a similar situation, I would most likely recommend that it gradually convert its system documentation as the team members make changes to the system over the course of time.
Of course not all systems need the level of documentation described above. My advice is to find the bare minimum of documentation that you need from both a project documentation and system documentation perspective and only add additional documentation when it hurts not to add it.
