Comprehensive Documentation Has Its Place


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.

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.