Writing A Document

---
name: writing-a-document
description: "How to shape a markdown document in this project: what the first paragraph carries, what a heading promises, and when to show a command instead of describing one. Use when writing or editing any .md file."
---

<!-- GENERATED by `plain-english render` from rules/default.yml. Do not edit. -->

# Writing a document

Applies to markdown written into a repository: READMEs, guides, reference
pages and architecture decision records. Not to chat, which has its own rules,
and not to a commit message or an issue body, which are shorter than anything
here would make sense of.

This is about the shape of a document. What not to write in one is already
checked: run `npx plain-english lint <file>` and fix what it reports.

## Say what the document is for before you explain anything

A reader arrives at a document to find out whether it is the one they need.
That decision is made in the first paragraph or by closing the tab, so it is
the one place background cannot go. Name the reader and what they will be able
to do, then start explaining.

Not this: Configuration in this project has evolved over several releases. Originally settings lived in a single file.
This: This page is for anyone adding a rule to the ruleset. By the end you will have one rule shipping with a test.

## A heading is a promise about what follows

Somebody scanning a document reads only the headings, so each one has to say
what its section settles. A heading that names a topic rather than a question
leaves the reader to open every section to find out which one they wanted.

Not this: ## Configuration
This: ## Where settings are read from, and which file wins

## Show the command, do not describe it

A reader can copy a command. They cannot copy a description of one, and they
will get it wrong reconstructing it. The same holds for a file path, a config
snippet and the output somebody should expect to see.

Not this: Install the package globally and then run the lint subcommand against your documentation directory.
This: `npx plain-english lint docs/`

## Write for one reader, not for everybody

What counts as too much detail is a fact about who is reading. A page that
serves a first-time user and a maintainer at once explains what one of them
already knows and skips what the other needs. Pick one, and link to the page
that serves the other.

## No heading with nothing under it

A heading followed by one sentence saying the section is coming later reads as
an outline somebody stopped filling in, and it teaches the reader that the
other headings may be empty too. Cut it, or write it.

## When you recommend something, say what it costs

A recommendation with no cost attached reads as marketing, and a reader who
later meets the cost stops trusting the page that hid it. Name the tradeoff
and the case where the other choice is right.

Not this: Use the blocking mode. It catches problems early.
This: Use the blocking mode when the repository is yours. It fails a build on a finding, so on a shared repository start advisory.

## Keep claims tied to the supplied evidence

Do not fill a missing fact with a plausible detail. Keep qualifications that
affect the conclusion, and label an assumption or judgment where the evidence
does not settle the point.

## Preserve the requested form when editing

When the request asks for a light or careful edit, change only clear faults.
Keep the document's meaning, genre, and useful structure.