Documentation Debt Is Paid by Your Readers#

An internal SDK with a decent API design, but the README contains only a single line of npm install and the sentence “refer to the source code for usage.” What’s the result? Every integrator spends half a day reading the source code, then asks the same questions in the group chat. If this SDK has 20 integrators, the 500 words you didn’t write cost society 40 person-hours.

The awkward thing about technical documentation is this: the people who write it well don’t directly benefit, and the people who write it poorly don’t directly suffer. That’s why it always gets queued behind “let’s ship the feature first,” and then never gets remembered again.

But this is exactly what makes writing documentation a skill with an extremely high return on investment. What follows is a set of things I’ve distilled from writing documentation and reading other people’s documentation over the past few years.

Step One: First, Figure Out What Kind of Documentation You’re Writing#

The biggest problem most people have when writing documentation isn’t their prose—it’s mixing four things with completely different goals into one document. The Diátaxis framework (proposed by Daniele Procida) lays out these four types very clearly:

The key point is that the writing rules for these four conflict with each other:

• Tutorials must be absolutely reliable, no step is allowed to possibly fail, so they must be verbose, must repeat themselves, and must do only one thing at a time;
• How-to guides must get straight to the point, skip explanations, and let knowledgeable people quickly get their answer;
• Reference manuals must be structured and searchable, with no narrative;
• Explanatory documentation should allow digressions, and can even say “this is actually a historical legacy issue.”

Mix them into a single README, and you get a Frankenstein like “a section of tutorial with an API parameter table suddenly inserted into it.” The reader gets lost at step 3, flips forward to look up a parameter, and gets buried by a wall of background introduction.

Practical advice: In your table of contents, split into folders by these four categories, not by module. tutorials/, how-to/, reference/, explanation/. Just making this split alone can take your documentation’s usability up a notch.

Five Principles You Can Put to Use Immediately#

1
Chapter 1 Overview
2
Chapter 2 Core Modules
3
  2.1 Client Class
4
  2.2 Config Class
5
  2.3 Plugin Interface

1
- Installation and initialization
2
- Upload your first file
3
- Handle upload progress
4
- How to chunk when uploading large files

1
import { createClient } from 'my-sdk';
2

3
const client = createClient({
4
  // ...other configuration
5
  retries: 3,
6
});
7

8
// error handling omitted
9
await client.upload(file);

Hand Documentation Quality Over to CI#

The principles are laid out, but relying on people’s self-discipline won’t hold up. The real way to keep documentation from degrading is automated checks. The minimum viable step: extract the code blocks from the documentation and at least do syntax checking.

The script below extracts language-tagged code blocks from Markdown and hands them to the corresponding parser for syntax validation (here using Node’s vm to check JS, and python -m py_compile to check Python):

1
// check-docs.js — extracts Markdown code blocks and performs syntax checks (requires Node 22+)
2
import { readFile, glob } from 'node:fs/promises';
3
import vm from 'node:vm';
4
import { spawnSync } from 'node:child_process';
5

6
// match ```lang ... ``` code blocks
7
const FENCE = /^```(\w+)\n([\s\S]*?)^```$/gm;
8

9
function checkJs(code) {
10
  // vm.Script only parses, does not execute, which is exactly what's needed for syntax validation
11
  new vm.Script(code, { filename: 'doc-snippet.js' });
12
}
13

14
function checkPython(code) {
15
  // use ast.parse to only parse without executing; a non-zero exit code indicates a syntax error
16
  const r = spawnSync(
17
    'python3',
18
    ['-c', 'import ast,sys; ast.parse(sys.stdin.read())'],
19
    { input: code, encoding: 'utf8' },
20
  );
21
  if (r.status !== 0) {
22
    throw new Error(r.stderr.trim().split('\n').pop());
23
  }
24
}
25

26
const files = await Array.fromAsync(glob('docs/**/*.md'));
27
let failed = 0;
28

29
for (const file of files) {
30
  const text = await readFile(file, 'utf8');
31
  for (const [, lang, code] of text.matchAll(FENCE)) {
32
    try {
33
      if (lang === 'js' || lang === 'javascript') checkJs(code);
34
      else if (lang === 'python' || lang === 'py') checkPython(code);
35
      else continue; // other languages are not validated for now
36
    } catch (err) {
37
      failed++;
38
      console.error(`✗ ${file}\n  ${err.message.split('\n')[0]}`);
39
    }
40
  }
41
}
42

43
console.log(failed ? `\n${failed} code blocks have syntax errors` : '✓ All documentation code blocks have correct syntax');
44
process.exit(failed ? 1 : 0);

Hook it into CI, and run it whenever documentation is changed in a PR:

1
name: Docs
2
on:
3
  pull_request:
4
    paths: ['docs/**', '**.md']
5
jobs:
6
  check:
7
    runs-on: ubuntu-latest
8
    steps:
9
      - uses: actions/checkout@v4
10
      - uses: actions/setup-node@v4
11
        with: { node-version: 22 }
12
      - uses: actions/setup-python@v5
13
        with: { python-version: '3.12' }
14
      - run: node check-docs.js

This check is shallow—it only validates syntax, not runtime results. But it catches the most common class of low-level errors—typos when hand-writing examples, unmatched brackets, a line lost during copy-paste. The next level up is truly executable documentation (running code blocks as tests, like Rust’s doctest, Python’s doctest, or mdBook’s test feature). That requires the examples themselves to be designed to be idempotent and side-effect-free, which is much more costly, and can be done after the project matures.

Finally: Treat Documentation Like Code#

Looking back at these points, they’re all really saying the same thing: documentation deserves the same treatment as code.

• Code has type checking, so documentation has code block validation;
• Code has code review, so documentation changes should also be reviewed, and during review you should ask “can a newcomer follow this and get it running?”
• Code has refactoring, so documentation’s table of contents should also be periodically rearranged according to readers’ usage paths.

There’s only one metric, and it’s very plain: find someone who has never touched this project, have them follow the documentation and do it once, and you watch from the side without speaking. Wherever they stop, that’s where the documentation needs to change.

Writing documentation isn’t “making up homework” for a project—it is itself part of the product.

References#

• Diátaxis — A systematic framework for technical documentation authoring: the division of the four documentation types, the core framework of the first section of this article
• Google Developer Documentation Style Guide: an industry reference for tone, terminology, and code example formatting, with very detailed rules on second person and active voice
• Docs for Developers: An Engineer’s Field Guide to Technical Writing (Jared Bhatti et al.): the complete process from reader research to documentation launch
• Microsoft Writing Style Guide: another widely cited writing standard, leaning toward product documentation