Is your software well documented?

TL;DR: When a software system is not well-documented it is difficult to maintain and more likely to be re-written from scratch. A well-documented software system is comprised of high-level, low-level, user, and developer documentation.

Over the years, I’ve been fortunate to be a contributor on extremely successful software projects as well as not-so-successful software projects. There are several factors involved in making a software project successful, including a bit of luck; however, the constant across all of the successful projects was that they were all well-documented.

A well-documented software system is comprised of high-level documentation, low-level documentation, user documentation, and developer documentation.

The following outlines the four documentation categories mentioned above.

High Level Documentation

  1. Catalog of externally maintained service dependencies and the considerations (i.e. expected number of concurrent users, uptime/downtime service level agreements) involved in choosing the service including pricing where applicable.
  2. Catalog of internally maintained services, their dependencies, and define back-pressure.
  3. Catalog all key stakeholders.
  4. Operations manual including who to notify when the system is down or broken, how to build, release, and deploy changes.
  5. Improvement proposals which include links to issues/stories depicting experiments and live implementations.

Low Level Documentation

  1. API documentation.
  2. Automated tests (unit/integration/end-to-end).
  3. Software formatting rules (automatic formatter and lint checking highly recommended).
  4. How to create and commit a set of changes and a link to the operations manual.

User Documentation

  1. User manual (HTML or PDF).
  2. User demos / tutorials.

Developer Documentation

  1. REST (or GraphQL or JSONRPC or SOAP) API documentation.
  2. SDK developer manual.
  3. SDK examples.

Prolonging the inevitable

In the abscence of well-defined context and scope, your software system is at risk for unbounded scope changes. Software engineering is much about recognizing and managing trade-offs and assumptions. When a software system is not documented it is difficult to reason about the state of the world and this, unfortunately, is where many software systems become so difficult to maintain that they get re-written from scratch.

As a software engineer, I would like to improve daily. This is why I advocate for systems that I contribute to, to be well-documented.