Productivity, PDF & Writing

Writing Documentation Developers Actually Read: Structure, Examples and Changelogs

Organise developer docs around four reader needs (tutorials, how-to guides, reference, explanation), write examples that run, keep a useful changelog, and check structure and links automatically with a tested audit script.

By Rajib Roy Published 5 min read

Most developer documentation fails in one of two ways. Either it is a pile of everything the author knows, in the order they thought of it, or it is a reference manual that never tells a newcomer where to begin. In both cases, the people who most need the docs are the ones who give up first.

The clearest fix I know is a framework called Diátaxis. This post explains it in practical terms, adds two rules about examples and changelogs, and shares a small audit script I wrote and tested that catches the structural problems automatically: missing sections, orphan pages and broken links.

Four needs, four kinds of page

Diátaxis starts from the observation that readers come to documentation with four different needs and that each needs a different kind of page. The framework's site names them as tutorials, how-to guides, technical reference and explanation, and says documentation should be organised around them.

KindThe reader is...It should be
TutorialLearning, with no idea yet what to askA guided lesson with a result at the end that works
How-to guideWorking, with a specific goalSteps to reach that goal, no theory
ReferenceLooking something upComplete, accurate, dry and consistently structured
ExplanationTrying to understand whyBackground, design reasons and trade-offs

The common mistake is mixing them. A tutorial that stops to explain design history loses the learner. A reference page with a story in the middle slows down someone who needs a parameter name. Keep each page to one kind, and link between them.

A folder layout that follows it

docs/
  index.md
  tutorials/
  how-to/
  reference/
  explanation/

The index links to everything, so a reader (or a link checker) can always find a page by following links from one place. That sounds minor and is not: a page nobody links to doesn't exist for readers. Naming conventions help too. I'd title how-to guides "How to ..." and tutorials with the result ("Build your first API client"), so a reader scanning a list sees the kind at once.

Examples are the documentation

Developers read the code block first and the prose second, if at all. So hold examples to a standard:

  1. Make it complete

    A reader should be able to paste it and run it. Imports, setup and the expected output belong in the block.

  2. Say which version

    State the version of the tool and runtime you ran it on. Examples rot silently.

  3. Tag the language

    A language tag on every fenced block gives you syntax highlighting and lets tools find the blocks.

  4. Test them

    If you can, run your examples in your continuous integration. An example that doesn't run is a bug in the docs.

  5. Show the failure too

    One example of the error a reader will most likely hit, with the exact message, saves more support time than three extra success examples.

Changelogs written for people

The Keep a Changelog guide makes a simple argument: don't dump a Git log into a changelog. Its recommendations, from the 1.1.0 version of the guide, are easy to adopt:

  • A file named CHANGELOG.md, with the newest version first.
  • An Unreleased section at the top to collect upcoming changes, which you move into a dated version at release time.
  • Group changes under Added, Changed, Deprecated, Removed, Fixed and Security.
  • Dates in ISO 8601 form (year, month, day).
  • Mark pulled releases as [YANKED], because people who installed them need to know.

The point of Deprecated and Removed is that an upgrade should never surprise someone. Say what is going away before it goes.

An audit script

Structure rots quietly: a page is added and never linked, a file is renamed and ten links break, a heading changes and an anchor stops working. This script audits a docs folder laid out as above. It checks that the four section folders and an index exist, that every page can be reached by following links from the index, that internal links and heading anchors resolve (using GitHub-style anchors: lowercased, punctuation removed, spaces to hyphens), that how-to pages are titled "How to ...", and that code fences have a language. Links and headings inside code blocks are ignored. Broken things are errors and convention breaks are warnings, and the exit status is 1 on any error so it can fail a build.

docs_audit.py

"""Audit a Markdown docs folder laid out in the four Diataxis sections.

docs/
  index.md
  tutorials/  how-to/  reference/  explanation/

Checks: the four sections exist; every page is reachable from index.md (no orphans); internal links and #anchors
resolve; how-to pages are titled "How to ..."; code fences carry a language. Exit status 1 on any ERROR.
"""
import re
import sys
from pathlib import Path

SECTIONS = ("tutorials", "how-to", "reference", "explanation")
LINK = re.compile(r"(?<!\!)\[[^\]]*\]\(([^)\s]+)\)")


def strip_code(text):
    return re.sub(r"^```.*?^```", "", text, flags=re.M | re.S)


def slug(heading):
    """GitHub-style anchor: lowercase, drop punctuation, spaces to hyphens."""
    s = re.sub(r"[^\w\s-]", "", heading.strip().lower())
    return re.sub(r"\s", "-", s)


def anchors(text):
    return {slug(m.group(2)) for m in re.finditer(r"^(#{1,6})\s+(.*)$", strip_code(text), re.M)}


def title(text):
    m = re.search(r"^#\s+(.*)$", strip_code(text), re.M)
    return m.group(1).strip() if m else ""


def untagged_fence(text):
    """True if any opening code fence has no language after the backticks."""
    in_fence = False
    for line in text.splitlines():
        if line.startswith("```"):
            if not in_fence and line[3:].strip() == "":
                return True
            in_fence = not in_fence
    return False


def audit(root):
    root = Path(root)
    out = []
    err = lambda m: out.append(("ERROR", m))
    warn = lambda m: out.append(("WARN", m))

    for s in SECTIONS:
        if not (root / s).is_dir():
            err(f"missing section folder: {s}/")
    pages = {p.relative_to(root).as_posix(): p for p in root.rglob("*.md")}
    if "index.md" not in pages:
        err("missing index.md")
        return out

    graph = {}
    for rel, p in pages.items():
        text = p.read_text()
        targets = []
        for t in LINK.findall(strip_code(text)):
            if re.match(r"^(https?:|mailto:)", t):
                continue
            path, _, frag = t.partition("#")
            dest = (p.parent / path).resolve() if path else p.resolve()
            try:
                dest_rel = dest.relative_to(root.resolve()).as_posix()
            except ValueError:
                err(f"{rel}: link leaves the docs folder: {t}")
                continue
            if dest_rel not in pages:
                err(f"{rel}: broken link: {t}")
                continue
            targets.append(dest_rel)
            if frag and slug(frag) not in anchors(pages[dest_rel].read_text()):
                err(f"{rel}: link to a heading that does not exist: {t}")
        graph[rel] = targets

        if rel.startswith("how-to/") and not rel.endswith("index.md") and not title(text).lower().startswith("how to"):
            warn(f"{rel}: how-to titles should start with 'How to' (title is {title(text)!r})")
        if untagged_fence(text):
            warn(f"{rel}: a code block has no language tag")

    # reachability from index.md
    seen, stack = set(), ["index.md"]
    while stack:
        cur = stack.pop()
        if cur in seen:
            continue
        seen.add(cur)
        stack.extend(graph.get(cur, []))
    for rel in sorted(set(pages) - seen):
        err(f"orphan page, not reachable from index.md: {rel}")
    return out


if __name__ == "__main__":
    found = audit(sys.argv[1])
    for sev, msg in found:
        print(f"{sev}: {msg}")
    print("OK" if not found else f"{len(found)} finding(s)")
    sys.exit(1 if any(s == "ERROR" for s, _ in found) else 0)

Does it work?

The tests build small documentation trees in temporary folders. A clean tree produces no findings. A tree with an orphan page, a link to a missing file, a link to a heading that doesn't exist and a missing explanation/ folder produces exactly those four errors. A how-to page called "Deployment notes" gets a warning, as does an untagged code block, and a link inside a code block is correctly ignored. All six pass.

test_docs_audit.py

import tempfile
import unittest
from pathlib import Path

from docs_audit import audit, slug


def build(files):
    tmp = Path(tempfile.mkdtemp())
    for rel, text in files.items():
        p = tmp / rel
        p.parent.mkdir(parents=True, exist_ok=True)
        p.write_text(text)
    return tmp


GOOD = {
    "index.md": "# Docs\n\n- [Tutorial](tutorials/first.md)\n- [Deploy](how-to/deploy.md)\n- [API](reference/api.md#create)\n- [Why](explanation/why.md)\n",
    "tutorials/first.md": "# Your first run\n\n```bash\nrun\n```\n",
    "how-to/deploy.md": "# How to deploy\n\nSteps.\n",
    "reference/api.md": "# API\n\n## create\n\nDetails.\n",
    "explanation/why.md": "# Why it works this way\n\nBackground.\n",
}


class Tests(unittest.TestCase):
    def test_slug(self):
        self.assertEqual(slug("Create a user (v2)"), "create-a-user-v2")

    def test_good_tree_is_clean(self):
        self.assertEqual(audit(build(GOOD)), [])

    def test_orphan_broken_link_bad_anchor_and_missing_section(self):
        files = dict(GOOD)
        files["reference/orphan.md"] = "# Orphan\n"
        files["index.md"] += "- [Gone](how-to/missing.md)\n- [Bad anchor](reference/api.md#nope)\n"
        del files["explanation/why.md"]
        files["index.md"] = files["index.md"].replace("- [Why](explanation/why.md)\n", "")
        msgs = " | ".join(m for _, m in audit(build(files)))
        self.assertIn("missing section folder: explanation/", msgs)
        self.assertIn("orphan page, not reachable from index.md: reference/orphan.md", msgs)
        self.assertIn("broken link: how-to/missing.md", msgs)
        self.assertIn("heading that does not exist: reference/api.md#nope", msgs)

    def test_how_to_title_convention_is_a_warning(self):
        files = dict(GOOD)
        files["how-to/deploy.md"] = "# Deployment notes\n"
        found = audit(build(files))
        self.assertEqual([s for s, _ in found], ["WARN"])
        self.assertIn("should start with 'How to'", found[0][1])

    def test_untagged_code_block_is_a_warning(self):
        files = dict(GOOD)
        files["tutorials/first.md"] = "# Your first run\n\n```\nrun\n```\n"
        found = audit(build(files))
        self.assertEqual([s for s, _ in found], ["WARN"])
        self.assertIn("no language tag", found[0][1])

    def test_links_inside_code_blocks_are_ignored(self):
        files = dict(GOOD)
        files["tutorials/first.md"] = "# Your first run\n\n```md\n[x](nowhere.md)\n```\n"
        self.assertEqual(audit(build(files)), [])


if __name__ == "__main__":
    unittest.main()

It has only run on those small trees. A large site with includes, generated pages or non-Markdown sources will need adapting, and I haven't tried that. And no script can tell you if a tutorial works. The best test for a tutorial is the same as for a README: hand it to someone new and watch where they get stuck, or follow it yourself on a clean machine.

A short checklist before you publish

  1. Does each page serve exactly one of the four needs?
  2. Can a newcomer find the tutorial from the index in one click?
  3. Does every example run, and say which version it ran on?
  4. Is there an Unreleased section, and are deprecations announced before removal?
  5. Does the audit pass?

Keep the README short and let it point at the docs, as GitHub's guidance suggests. The README template post covers that front door.

What I haven't verified

  • The audit script on a large documentation site, or on MDX, reStructuredText or generated API docs.
  • That Diátaxis suits every project. Very small projects may need only a README and a reference.
  • Any claim in the framework's own site about adoption or results. I describe its structure only.

If your documentation needs a reorganisation, or you want checks like these in your build, I take on that kind of work.

Build with me

Want your docs reorganised?

I restructure developer documentation, write missing guides and add automated checks to your build so the docs stay accurate.

See services Get in touch

What I ran this against

  • Python 3.13.5 on Linux, standard library only, run on 17 November 2026. 6 tests pass.
  • The audit script was tested on small temporary documentation folders built by the tests: a clean tree, a tree with an orphan page, a broken link, a bad heading anchor and a missing section, a how-to page with the wrong title style, an untagged code block, and links inside code blocks. It has not been run on a large real documentation site.
  • The structure is taken from the Diátaxis framework as described on its website. I have not applied it to a real project for this post.
  • The script checks structure, links and a few conventions only. It cannot tell you whether the documentation is clear or correct.

Sources checked

  • Diátaxis, "A systematic approach to technical documentation authoring" (four needs and forms: tutorials, how-to guides, technical reference and explanation): diataxis.fr, read 17 November 2026.
  • Keep a Changelog, version 1.1.0 (changelogs for humans, an Unreleased section, change types Added, Changed, Deprecated, Removed, Fixed and Security, ISO 8601 dates, yanked releases marked [YANKED]): keepachangelog.com, read 17 November 2026.
  • GitHub Docs, "About the repository README file" (what READMEs typically cover; README surfaced from .github, the root or docs, in that order; content beyond 500 KiB truncated; auto-generated table of contents; relative links, with links starting with / relative to the repository root; link text must be on a single line; longer documentation suits wikis): docs.github.com, read 17 November 2026.