Keeping Software Documentation in Shape

Software engineers love to code and are usually less keen on maintaining documentation. Therefore, it's usually hard to keep documentation up-to-date. The most common problems I see with software-related documentation are outdated content and poor structure. While it's possible for engineers to improve in these areas, to reach a good level of quality you need to have a dedicated person focusing on this task, such as a technical writer.

Like with code, documentation requires clear rules, templates, and a well-defined review process. Where technical documentation is primarily written by engineers, the best way to keep it in good shape may be to treat it as code. You should have a design guideline, follow patterns and best practices and define who will take the lead and outline a vision.

But what if we take documentation to code completely? Across the eBay Classifieds Group, I see more and more teams taking this approach. Primarily we use three instruments when working with documentation and not code:

"For me, lightweight ADRs, code documentation inside repositories and postmortems should be the main documentation instruments for Software Engineers."

Every rule has exceptions. Technical blog articles, global component diagrams, guidelines, and RFCs may require other approaches.

Lightweight Architecture Decision Records

One thing that can cause confusion is when design documents aren't updated. The team has a discussion about a particular component design. One member of the team creates a document later on. The document lives on its own and may occasionally get updated. You never can be sure whether the document is up to date. Usually, you treat the last modified date as an indicator of freshness.

"But what if we make a habit of not updating the documentation?"

Michael Nygard proposed the notion of immutable one-off design documents known as Lightweight Architecture Decision Records (ADRs). ADRs are meant to document architecture decisions along with the known constraints that lead to this decision at the time it was made.

The important aspect of an ADR is the date when the decision was taken. You always know that an ADR is immutable and the date shows how relevant it is. You never update existing ADRs, instead, you create a new ADR if thinking has changed.

Of course, ADRs are no replacement for other types of documentation, such as API docs, but they can significantly reduce documentation hassle by making mortal documentation explicitly mortal and time-stamped.

Code Documentation Lives Near the Code

The other kind of documentation is best treated as code and stored in the same repository alongside the logic it describes.

The best example is the API documentation. To keep changes in code and documentation in sync you could place those things together. A single pull request that bundles documentation and code changes together makes it easier to keep both in sync. In addition, your documentation gets a higher quality bar. Now it needs to pass code review.

The most common format for this kind of close-to-code documentation is a lightweight markup language such as Markdown, as commonly used in README files. The API-specific documentation might have a different specific format such as OpenAPI (formerly known as Swagger).

If you use fixed releases or versioning schemes such as Semantic Versioning, having documentation inside the code repository ensures both share the same lifecycle, as the code version and related documentation are automatically linked.

But there are other good reasons for Software Engineers to use plaintext.

Postmortem Documentation

Changes are probably the most frequent reason for failures and incidents -software failures are normal. I like the Error Budget concept from Google Site Reliability Engineering practices. If you don't have any incidents (which doesn't necessarily mean downtime or visible impact for the majority of users), most likely you operate at a very small scale or your system is in maintenance mode without active development.

Anyway, we should strive to minimize the number of failures. One way of doing this is to learn from the past and identify your own mistakes. The nice and friendly way of doing so is Postmortem Documentation. Postmortems are our "lessons learned" and document not only the failure reason but also ways to improve the situation in the future to avoid the same mistakes.

We should learn also from failures which were mitigated by redundancy -such as having a second data center or canary releases. Moreover, Postmortems promote responsibility and accountability for resilience.