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.
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.
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.