Where help lives: help systems and docs-as-code¶

Exercise help-systems-docs-as-code-annex.pdf · PDF

Have you ever read the manual of your phone? No. Have you searched "how to..." for an app this week? Probably. Have you hovered over an icon to find out what it does? Almost certainly, without even noticing. So you do read documentation, all the time. You just never read it where its author expected.

Your app can already draw screens, save data and print a report. Nobody but you knows how. This unit fixes that by putting the help where the reader already is. This page draws the map: where help can live, which tools produce it, and how to write it once instead of three times.

The game box¶

Keep one picture in your head for the whole unit: a board-game box.

Open the box of Catan (Klaus Teuber, 1995). Its rules say on the first page that they come in three parts: a Game Overview on the back cover, the Game Rules to start playing, and an Almanac to look things up during the game. There is a fourth kind of help that nobody calls documentation: the text printed on the cards themselves.

Every piece of the box has a twin in your app:

Two words need separating:

Documentation is everything that explains the app to someone who is not you. Help is the documentation the user meets while using it.

And "someone who is not you" comes in three kinds. Keep them in a column in your head, because every page you write is for one of them:

Three places where help lives¶

Open LibreOffice Writer and press F1. A help window appears. Where did that text come from: your disk, or the internet?

Both answers have been true. Windows 3.0 (1990) shipped help as WinHelp files (.hlp). Microsoft released HTML Help (.chm) as its replacement in 1997. Today F1 usually opens a web page. The formats change, but the question stays: where should this sentence live so the reader finds it?

There are three answers:

Which one is best? None. A real product has all three, and they all say the same thing. That is exactly the problem the rest of this page solves.

Help-generation systems¶

You do not write a website or a PDF by hand. You write a source, and a tool produces the result.

A help-generation system is a tool that takes a source and produces help in a format.

For each tool, ask two questions: what goes in, and what comes out?

Two of these have a story worth knowing. Pandoc dates from 2006. Its author, John MacFarlane, is a philosophy professor at Berkeley, and the project describes itself as "a universal document converter". Zensical is far younger: Martin Donath and the team behind Material for MkDocs announced it on 5 November 2025. It is younger than your phone and it is still before version 1.0, so check its documentation when something looks different.

Notice the last row. Not everything has a generator. If the answer must appear next to a form field, no tool writes it for you: it is code, in your app.

Docs-as-code¶

Lessons on this site live in plain files like docs/tema-1/apple-hig.md. Change one word, save, and zensical serve reloads the page. Run git log and you see commits, exactly like code.

Docs-as-code means writing documentation with the same tools as code.

The Write the Docs community lists those tools: plain text markup, version control, code reviews, automated tests and issue trackers. For you, it means Markdown files, in the same Git repository as the app, built by commands.

The format is Markdown, created by John Gruber in 2004. It is plain text that you can read before any tool touches it, which is why it survives every change of tool. Write it once and let two tools read it:

flowchart LR
    S["<b>docs/*.md</b><br>one text, written once"]
    S -->|"Zensical"| W["<b>Website</b><br>the rules, online"]
    S -->|"Pandoc + Typst"| P["<b>PDF</b><br>the rules, printed"]

That idea is called a single source: every format is generated from one text, so a correction reaches all of them. It is the same promise as the variables you met in Figma: change it in one place.

A few more wrong ideas you will hear:

The docs map of your app¶

Before writing a word, draw the plan. A docs map is a sitemap for your documentation: one card per page. Every card answers four questions:

1. Who reads it?
2. When do they read it?
3. Where does it live: web, PDF or in-app?
4. Which file produces it?

Here is the map of NoteBox, the small notes app used as the example throughout this unit:

Look at the last row. It is not a docs page, it is a component. Help on the screen lives in your code.

Now draw yours, with seven cards at least: one tutorial, two user-manual tasks, one reference page, one page to install, configure and administer, one data page, and two things marked in-app. Four mistakes are common:

• Cards named after screens ("Settings", "Home"). Ask what the reader wants to do. A user-manual card is a task: "Export a report as PDF".
• The reader is "the user" on every card. The installation page is for whoever installs. The data page is for a developer or an administrator.
• Everything is web and PDF. Which page would somebody really print or attach to a delivery? Usually the user manual and the admin manuals, not the tutorial.
• Nothing is in-app. Which field of your app did your classmates fill in wrong when they tested it? That one.

Your map is more than a drawing. It becomes the table of contents of everything you write in this unit.

Key takeaways¶

• Help lives in three places: web docs, PDF and in-app. A real product has all three, saying the same thing.
• Documentation explains the app to someone who is not you, and it has three readers: end user, administrator and developer.
• A help-generation system turns a source into a format. For each tool, ask what goes in and what comes out.
• Docs-as-code means Markdown files, in Git, next to the code, built by commands.
• A single source is written once and generated into every format, so the versions cannot drift apart.
• A docs map gives every page a reader, a moment, a format and a file.

Quick check¶

Now you have a map. In the next lesson, Zensical site and Pandoc PDF, the map becomes a real website and a real PDF.