System Documentation

What Is System Documentation

System documentation is information about an as-built solution and acts as a reference for future maintenance or update efforts. It is organized based on system functionality rather than when changes were made to the system, making it easier for people who maintain the solution to find the information they need quickly.

While the solution itself (and tests written against it) can provide a great deal of information, there will always be a need for additional sources of information, especially for aspects that are not readily apparent. This information can take many forms, but I usually like to have some combination of the following:

• Glossary: definitions for the commonly used terms in the domain in which the system operates
• Business rule catalog: descriptions of the rules, though without indicating how those rules are enforced (that information is typically noted in one of the other artifacts or represented by tests)
• Metadata: data about the data that the system collects, stores, and provides
• Process flows: descriptions of the business processes that the system supports
• User interfaces: descriptions of the operations behind the scenes or the enforcement of business rules related to the user interface
• Permissions: a description of which roles can perform which functions in the system

An Example

For the conference submission system we use GitHub for source control and for any documentation we need to communicate during the course of changes we are making. Each change is listed as an issue, and any specifics are described in the back-and-forth of the comments we use to clarify expectations.

We also keep the examples we write for each item. These examples are organized based on system features and serve as my first point of reference when we are investigating a case where the submission system does not seem to be working properly. Nine times out of ten, the defect ends up being a scenario that we did not account for during our development work, evidenced by the lack of an example.

To supplement the examples, and my bad memory, I’ve also created spreadsheets that reflect permissions, as well as notes about the specific notification messages that go out under certain circumstances. These tend to be the main pieces of information that are useful to store at a point of reference other than GitHub or the system itself.

When to Use System Documentation

System documentation is helpful anytime you have a solution that will be maintained and updated through its lifetime. In a broad sense, this applies to most systems built or implemented by an IT organization. System documentation is especially helpful when the system is maintained or updated by a different team from the one that originally built it and can even be useful for solutions that are built and maintained by the same team, especially if the solution is expected to have a long life (say, more than a year).

Why Use System Documentation

Creating documentation that describes the system is not essential for delivering value right now. It is, however, extremely helpful in the long run for those who are trying to maintain and update the system—helpful enough that you should do it, but not so tremendously valuable that you should spend an inordinate amount of time or effort on it. The same goes for documentation done during a project. In that case, the main purpose is to aid the building of shared understanding.

In both cases you create documentation with a purpose, and once you know that purpose it’s usually a good idea to structure the documentation based on its purpose. In the case of system documentation, you want it to reflect the current state of the solution as built, and you want it organized in an intuitive way—most likely based on how the solution itself is organized.

How to Use System Documentation

1. Determine who will be the primary audience of the system documentation. Usually the audience is the people who will maintain the solution on an ongoing basis. This may or may not include the team currently working on the solution.
2. Treat those people as another group of stakeholders and find out what their needs are in conjunction with supporting the solution. Find out what information they need, what would be a good way of organizing it for them, and in what form they would like the information to be available (wiki, documents on a shared drive, three-ring binders, etc.).
3. Identify a plan for creating the system documentation that you are confident you will follow. Most teams create system documentation either by creating backlog items to create the system documentation or by including updated system documentation in their definition of done. Using the definition of done in this way usually increases the likelihood that the documentation will actually get created, since backlog items calling for the creation of system documentation may never get pulled into an iteration.
4. Establish an agreed-upon repository for system documentation that is accessible to the people who need it and is easily updatable. Your organization may already have standards in place for what this repository should look like.
5. Create it and keep it up-to-date.

Caveats and Considerations

The need for documentation comes from two places: customers ask for it (user guides, help, sometimes system documentation), or the team finds it helpful for doing their job (project documentation and system documentation).

It may be helpful at this point to differentiate project documentation from system documentation. I use the term project documentation to refer to any documents the team uses to help

communicate or remember changes in 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:

• Backlog items: 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: wireframes, data models, or process flows that 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: further descriptions of the stories that weren’t covered by the examples or models.

Project documentation is temporary in nature; it is used to describe the specific changes that are needed during the effort and thus depends on a specific current and future state. I prefer to make project documentation as light as possible while still meeting the needs of the team. The definition of ready provides a definition of “just enough” for purposes of project documentation, then I create separate system documentation to act as a reference for future efforts. This software documentation contains information useful for maintaining a solution in an ongoing fashion and may contain some information originally created in project documentation.

Backlog items may be used as a source of release notes, and the examples, models, and acceptance criteria may provide a source for system documentation, but these things do not constitute the system documentation itself.

Many teams plan to use design documents and technical requirements as system documentation. If they do this, they certainly should update those documents to reflect what was actually built. But that doesn’t change the fact that the documentation is organized based on when changes were made and thus may be hard to parse when working on the next effort.

There are mixed opinions on whether documentation is valuable or not. In some respects system documentation has gotten a bad reputation. In many approaches documentation was perceived as a measure of progress, and many delivery team members would view it as something they had to do—essentially a check on the list of required steps so they knew how the project was progressing. Agile approaches suggest that teams use a different measure of progress—value delivered—relieving that burden from documentation.

Additional Resources

Best Practices for Agile/Lean Documentation Scott Ambler (though I still insist there is no such thing as “best practices”)

Comprehensive Documentation Has Its Place StickyMinds.com by Kent J. McDonald

Business Analysis Template Toolkit from Bridging the Gap (Affiliate Link).

You may find the templates for Business Process, Data Feed, Glossary, and User Interface helpful starting points for some of your system documentation.

If you like to use Use Cases to represent functionality such as the team described in the Comprehensive Documentation Has its Place article, the Use Case Template and Use Case List may be helpful as well.

The Death of the User Manual

Over the years Andrea Saez has created various product help resources, so she wrote a little something about how to optimize your own documentation so that it’s actually helpful (and hopefully, people will actually start reading!)

How Google, Twitter, and Spotify built a culture of documentation

Many technical problems ultimately turn out to be people problems, and a lack of good documentation is no exception. Writing and maintaining documentation is a habit that needs to be encouraged and nurtured. The unfortunate truth is that no amount of tooling is going to help without a culture of documentation. Nik Begley looks at how 3 high performance engineering companies, Google, Twitter, and Spotify, handle their technical documentation and built a culture of documentation.

Want to know more?

If you learn better with video rather than reading, you may want to check out Analysis Techniques for Product Owners Live Lessons, a set of video training sessions that show you how to apply analysis techniques to product ownership. Lesson 6.5 focuses on system documentation.

Analysis Techniques for Product Owners is available on Safari – O’Reilly’s online learning platform. Sign up for a 10-day free trial to view the video lessons.