The art of writing (good) documentation

Writing documentation is not fun. But it **is** important. How do you write documentation that survives the test of time?


Posted on May 20, '21

Up until recently, I’d considered documentation irksome and something for “hand-overs”. I believed that clean, commented code should be self-documenting. Recent experiences have made me reconsider my opinion.

Say you have or are a new engineer on the team. With no clue about the tech stack, the terminology and the “tribal knowledge”. So what happens in the absence of a “tribal”? Long, painful hours of reading code, following dependencies to try and distill out the intent.

Code is a bad way of documenting intent. Code is an implementation of intent. Documenting what code is supposed to do, in a language understandable to all, leads to better validation and visibility. Code can be buggy, but it is hard for validated, trusted documentation to be buggy.

Documentation is great for:

  • effective onboarding
  • effective debugging
  • stakeholder management
  • documenting the why, capturing decisions and reasoning
  • retrospectives

This post outlines some things to consider while writing documentation.

Planning

Plan the structure

Good stories have good structure. They consider the audience and pace the information. Documentation is the story of your code. The goal of documentation is to serve the reader. To provide answers. And to do that as effectively as possible.

There is nothing more frustrating than going through large pieces of text, full of unexplained terminology - only to realise it wasn’t relevant.

Add an outline

Add a list of contents at the outset, that’ll allow the user to immediately navigate to the section most relevant to them.

Do not skip the introduction

Add an introduction, to set context and introduce stakeholders.

Goal of this section is to,

  • allow the reader to quickly determine if this documentation is relevant to them,
  • if they will get the information they are looking for and
  • how to find required information fast

Here are some key points to include,

  • Describe what the project is
  • What does the project do
  • What technology the project uses
  • What are the key stakeholder workflows that the project affects
  • How does it relate to the total infrastructure
  • What does this documentation cover
  • Who should read this documentation

This is good place to interlink with any parent/sibling documentation. Also provide links to any design documents, product specfications here.

This section helps identify the key stakeholders at this point - the main development teams, the consumers of this code and the business areas that the code affects. Elaborating on this section also helps the author of the documentation think about who their target audience is. This helps tailor the writing, add/subtract any details and missing context and ascertain.

Follow Progressive Information Disclosure
  • Explain terminology, fundamental concepts building blocks early
  • Keep information scannable - by using header heirarchy
  • Information flow should be drilldown - broad to details

About Writing

Overexplain - focus on the why

Whenever explaining logic, explain the rationale behind that logic. Documentation is a great place to capture business and technical intent in one place.

When explain technical architecture or decisions, always have a section that outlines the business (soft) requirement that led to that decision.

Use Templates

When explaining technical details, use templates. Details about common software elements like databases, queues etc, should have the same layout of documentation. For eg, a queue can be described with a table, with the same headers, covering the same information.

This helps reduce cognitive load for the reader. Once they are used the format, they already know what to expect and where to look.

Practical Views

Add practical examples, expected payload formats wherever possible. For interactions and processes - outline the end-user impact, the design language and specify contracts

Use Visualizations - Diagrams, Tables and Tools

Diagrams, charts, tables etc help provide structure to information to make it easily scannable.

A picture is worth a thousand words

  • (Over) Use tables, schemas and diagrams
  • Simplify - use only one per concept
  • Name the diagrams, tables (be mindful of making it human-readable)
  • Add legends to diagrams
  • Use standard symbols for technical components (keep this consistent across all documentation)
  • Identify and add diagrams for key workflows and critical paths
  • If possible, embed videos
  • Think about the layout - documentation doesn’t need to be a boring, linear dump of colorless information
Complementary Sections

It is easy to forget the smaller details in the big picture of things. But keep the documention comprehensive, as much as possible. Adding simple sections for monitoring, links to dashboards, other documents that provide additional context, a glossary and an FAQ section as simple ways of achieving that goal.

Maintenance

Change is the only constant in the world.

Code will change. Intent will change. Technology will change. New features will get added. Here are some ways to ensure that documentation remains fresh and updated.

  • Use documentation as an onboarding tool: For every new member on the team, use the documentation as a single entry point.
  • Comment your code: Add inline comments and cross-link to documentation
  • Plan for periodic syncs with other stakeholders; Have them draw out mentals models, to evaluate the efficiency of your documentation