Docs that answer a question

A table of the questions the owner actually asks, with the file that answers each one, beats a long tour.

Most project documentation is written in the order the author built things: setup, then structure, then usage. The reader arrives with a question instead, and has to guess which chapter holds the answer.

A dark placeholder card reading Docs people read

Lead with the question

The README here has a small table near the top. Each row is a task phrased the way the owner would say it, and the file and section that answers it.

I want to Read
Change my name or bio docs/usage.md, "Where the text lives"
Write a new post docs/usage.md, "Writing a post"
Publish on my domain docs/deploy.md
Publish without Cloudflare docs/deploy.md, the last section

Four rows cover what four separate conversations used to cover. Nothing is explained twice, because the table points at one place per question.

A dark placeholder panel showing the question table

One document per kind of question

Document Answers
usage.md What do I edit to change what the page says
deploy.md How does this reach my domain
architecture.md Why is the code shaped like this
security.md What is protected, and what is not
decisions.md Why this option and not the other

Mixing them is what makes a single docs/ file turn into a wiki nobody reads.

Troubleshooting next to the task

The last section of each document is a table of symptoms. The reader who is stuck does not want theory, so the row gives the raw error text, the likely cause, and the command that fixes it.

Put the error message in the document word for word. That is the string the reader searches for.

Write down what is not included

deploy.md ends with a list of things left out on purpose: no healthcheck, no access log, no analytics, no upload endpoint. A reader who knows what the design does not do stops looking for it.

Keeping it true

Documentation ages the moment a page is added, so the change that adds a feature also edits the table that points at it. The rule is simple: a new page or a new route is not done until the question table and the publishing checklist mention it.

Back to all posts