Software Documentation is Software

How to manage software documentation

2022, Jan 08

Software documentation is often neglected. However, the software is nothing but knowledge described as machine instructions by using a programming language. This knowledge doesn’t start at the machine instructions level, it starts with the information we have about specific real-world needs.

Describing the knowledge at the initial abstraction level and successfully enriching and transforming it into lower abstraction levels is the essence of the software development process. Still, most engineers don’t see this documentation as an essential part of the software we build.

That is just about non-user documentation. Yesterday, my Ember Mug² arrived. It had a manual. I had to connect it to my phone, which also had a manual. When writing software, we often need to provide installation manuals, user manuals, troubleshooting guides, FAQs, compliance reports, licenses, etc. All these are documents that need to be managed and evolved with the software.

Product, Project, and Organizational documentation lifecycle

Software documents have their lifecycle determined by what they refer to.

Product documentation is software documents such as end-user documentation, technical specifications, requirements, support, and installation guides. They will have the same lifecycle as the scope they refer to. If your software has separate manuals for each component, once the component is phased out, the manual is phased out. If the component is updated, the manual will require updating.

Because of this lifecycle, product documentation is usually stored in internal portals or wikis, not issue trackers. When needed, issue trackers usually have links to information kept in more persistent tools. This allows multiple initiatives to update the same documentation over time without losing sight of where it is.

In case you want to read more about the importance of troubleshooting guides and FAQs, please read this topic from a previous post (the link below will direct you to the specific session):

Project documentation is software documents such as testing and project plans, estimates, budget, etc, have their lifecycle attached to that context. If a project ends or an epic is finished, all this data is kept for historic reasons, but they won’t require updates, there are no phase-outs if the software is phased out.

This documentation is sometimes on issue trackers due to the temporary nature they have. Issue trackers have been heavily used to manage projects and initiatives, making this kind of information extremely relevant in that context. However, I recommend collecting data (even if summarized) and storing them in internal portals/wikis (or at least providing a link there to queries on the issue tracker) for historic reasons, allowing future analyses.

Organizational documentation is not software documentation, however. They are not tied to the software, but to how the organization structures itself to perform activities. It’s composed of processes, directives, and policies around the activities that are executed when providing services and building products.

A good example of organizational documentation that is often not seen as such is templates. The templates used to build product and project documentation are organizational documentation as well. This type of asset is often overlooked, but it not only allows for standardization across components, product areas, and projects.

Templates work in the same fashion as a common language, allowing people reading the documents to know exactly what the information means, how and when to use it. Because of it, ambiguous or incomplete templates can cause issues with projects, estimates, and even defects on the product.

The lifecycle of organizational documentation is tied to the organization itself. Organizational restructuring, acquisitions, changes in the line of business, in the strategy, or simple changes to improve the organization’s performance to meet new organizational goals will determine the need for updating or even phasing out organizational documents. In this post, I will not cover organizational documentation. It’s just important to differentiate this from the other documentations we deal with when engineering software.

Because of the persistent nature of organizational documentation, it’s usually documented in internal portals and wikis. Issue trackers are not suitable for this kind of information.

Documentation traceability and versioning

Documents have different traceability and versioning needs, depending on their lifecycle and the organizational needs determined by policies, market requirements/client demands, and external regulations.

Product documentation

Product documentation evolves with the product. Whenever there is a change in requirements, the change needs to propagate to technical specifications, manuals, supporting documentation, tests, and code.

Therefore, it is important to know what is connected to what. I have found situations where only when it reached the point of changing the code, the team was able to determine that making the necessary change would cause a conflict with another feature. At that point, the team could not decide what to do.

Thankfully, we could check the commit related to the other code and find the issue tracker ticket Id. From there, we found the ticket that told us the related epic, the documentation, the requirement provider, and we were able to negotiate a solution.

Because the documentation has an impact on the software and vice-versa, it is important to be able to trace all the assets that are related so that changes can be carried out consistently.

This also helps with regression scope definition and regulatory compliance.

In some markets, products may have to be maintained at different versions simultaneously. In this scenario, it’s important to have specific versions of the documents associated with each version of the software.

In this way, the organization can investigate find defects and opportunity improvements across the different versions and report on feature availability and regulatory compliance with each version, as well as provide customer support (as customers on different versions will have different issues and needs).

Project documentation

Project documentation is usually simpler. A simple history of the modifications usually covers most of the needs of any organization. Project documentation tends to have a much shorter life, requiring updates when plans become outdated.

Documentation may become outdated if there are changes in resources availability, participants (internal or external), when estimates are refined to reflect the project status, etc.

Usually, it’s enough to identify who needs to be communicated about the need for an update, who should update it, and who should be informed that the update was made.

These documents can be archived at the end of the project.

Documentation Quality

If your requirement has a defect that nobody notices, the code will implement the defect behavior, the test will verify that the code implements the requirement correctly (i.e., the defective behavior is present) and it will become a defect in production after release.

It happens not only to requirements, therefore we need to be able to assess the documentation quality. I talk a little bit more about the defect propagation in a topic on a previous post (the link below will take you straight to the corresponding session):

Multiple practices can be employed to verify and find defects in different document types. From reviews to inspections, there are ad-hoc readings, walkthroughs, checklists, reading techniques such as perspective-based readings, each one with different techniques. Collecting information such as defect density per document type will allow you to determine which artifacts are more prone to contain defects. From there you can decide to improve templates, provide training, automate the task or replace it with something else.

If you want to read more about how to AVOID defects instead of only trying to catch them later, you will want to read the session about it by clicking the link below:

Definition of Done

In Agile methodologies, we usually apply a checklist called “Definition of Done” (DoD) as criteria to determine that a certain story is complete.

While many people think they need to include development activities in the DoD, we don’t. One example is “Testing”. Today, it’s almost standard to have a criterion to make sure that the software was tested. I don’t think anyone would simply “miss” that. If engineers could simply forget about testing, then why don’t we list “code reviews”, or “requirements specified”, or any other activity of the development process?

What we really miss in the DoD are the artifacts that will be required AFTER the story has been completed, i.e., all the artifacts that need to be produced in the scope of the story. Artifacts that are required to complete the story will necessarily be produced during the execution of the process. So, guess which artifacts are usually missing from the DoD? You got it: Documentation!

Include in your DoD your technical manuals (installation/deployment guides), your support documentation (FAQs and Troubleshooting Guides), your user documentation (manuals and licensing information).

Sometimes, while engineers are coding or testing, they have questions that raise information that wasn’t available in the requirements. Make sure your DoD has a check item to update the requirements with the information that was learned during the story development.

Wikis

Wikis have become the industry-standard tool for documentation. Its ability to manage collaborative work is unparalleled.

Wikis, however, pose a big challenge in versioning, especially when software versions need to be kept with the corresponding documentation for that particular version.

I’ll provide a very simple and very effective way to achieve that: Create a root page that explicitly states the release version every time you start working on a new release and copy all the documentation to that space.

Let me know in the comments if you have better tips to maintain different versions in a Wiki.

If you like this post, please share it (you can use the buttons in the end of this post). It will help me a lot and keep me motivated to write more. Also, subscribe to get notified of new posts when they come out.

 Back