As code changes, documentation becomes stale over time.

This happens at big companies. This happens at small companies. Unlike code, documentation is not compiled or tested. The code is executed. If the code execution fails or produces incorrect results, it is fixed with much higher urgency.

Too much documentation, like too many tests, is a bad idea. It slows down engineers who might not be well-versed in composing English proses. Further, if documentation is say about 90% accurate, it is useless for onboarding or training new engineers, as they won’t know what 10% portion is incorrect.

What’s a better approach?

  1. Minimize documentation - Like tests, write documentation along the axis of minimum change. Provide the overarching overview of the system. But don’t specify the database schema in the documentation, link to the code instead. Similarly, don’t specify precise tools like pip or yarn either as these tools keep evolving. Just link to the correct command file like Makefile or package.json. If the link fails to resolve, it would be an immediate indicator that documentation is obsolete.
  2. Automate documentation generation - Tools like pandoc, go docs and Java docs are great at generating automated documentation from the codebase. This is less likely to go stale. Even for external APIs like OpenAPI, one can automate documentation generation by adding relevant hooks directly in the codebase. For example, libraries like fizz (for Go) and swagger-autogen (for Node JS) can generate openapi.yaml and openapi.json spec directly from the code. Add a CI task to automate this generation and then the specification would never drift away from the source code.