Writing Style

How to write prose for this project: botdocs, and how to review and edit blog posts in mandocs/posts/. Read this before writing or reviewing either. It is a distillation of a few well-known sources, listed at the end; when this guide is silent, they are the tiebreaker.

Contents

The one rule

Write for a reader with a problem, not to record what you know.

The reader does not care that a thing was done or how much effort it took. They care about something that is costing them: a slow loop, a confusing rule, a design that will not scale. A document earns its length by changing how the reader understands that problem. Before writing, name the reader and the problem in one sentence each. If you cannot, you are not ready to write.

Know which kind of document you are writing

Most muddled documents are two or three kinds of document mixed together. Pick one; link to the others.

A plan that becomes implemented should eventually be distilled into an explanation or reference doc. Do not keep patching a plan into a spec.

Give it a spine

A document that proceeds "and then, and then, and then" loses the reader. Connect sections with but and therefore instead:

We have X, and it does Y. But Z goes wrong. Therefore we try W. But W costs V. Therefore ...

Each section should exist because the previous one left a problem open. If a section does not advance that chain, it is a digression: cut it, shrink it to a sentence, or move it to its own document.

This applies to blog posts most of all. "What I did on the way" is not a spine. Dead ends belong in the story when they teach something -- when the but is the interesting part -- not because they happened.

Openings

The first paragraph does four jobs, in this order (Minto's SCQA):

  1. Situation -- what the reader already knows or accepts.
  2. Complication -- what is wrong, missing, or costly about it.
  3. Question -- usually implicit: so what do we do?
  4. Answer -- the thesis, stated plainly.

State the answer early. A reader who knows where a document is going can read the evidence as evidence; a reader who does not is just accumulating facts. Mysteries are for fiction.

Do not open with throat-clearing ("This document describes...", "In this post I will..."), background the reader already has, or the history of how the document came to be.

Endings

The opening makes a promise and the ending shows it was kept. A reader who got the answer in the first paragraph does not need it again. They need to see what it amounts to now that they have the evidence.

The ending is the document's stress position, by analogy with Gopen and Swan's rule for sentences: what is there is what the reader leaves with. Do not end on a hedge, an acknowledgment, or a list of minor future work.

Write the bookends first

Before the middle, draft the opening and the ending: the problem and the answer you expect, and where that answer leaves the reader. The middle is then the spine from one to the other. A section that does not move the reader from the first toward the second is a digression.

Expect the ending to move. Drafting is how you find out what you think, so the claim that surfaces at the end of a first draft is often the real thesis. McEnerney and Williams both make this point. When that happens, move it to the opening, and write a new ending to go with it.

A post started before the work is done gets the same treatment: bookends holding the expected answer. When the results come in, check them against the bookends. If they disagree, the disagreement is usually the better post.

Sentences

From Williams and Gopen & Swan; these do most of the work of clarity.

Cutting

Draft long, then cut a third. Things to cut first:

Botdocs conventions

Observed from the existing docs; follow them.

Blog posts

Posts live in mandocs/posts/ and Brian writes them. Bots do not draft posts; they review and edit them when asked. The job is to make the post more itself, not to make it sound like a bot wrote it.

Audience

Nobody uses Datalove, so the reader is not a Datalove user. The primary reader is a practitioner who has the same problem the post is about: language implementers, people building interpreters, JITs, and runtimes in Rust, and PL enthusiasts. Potential customers, employers etc read the same posts and judge them the same way, by whether peers find them worth reading; do not write at them.

Make the problem general and Datalove the worked example. "How I made drops precise in Datalove" is a devlog; "Static drops for linear types, and where dynamic tracking still wins" is a post someone building a different language will keep.

The test: would someone who will never run Datalove learn something they can use? If yes, it is a design post. If no, it is a devlog post -- a short note on what landed, which is fine, but should not be dressed up as more. Checkpoints and releases are milestone posts. The builder rejects any other category; new ones are declared in crates/datalove-cli/src/main.rs.

Two other audiences, served differently:

Posts are often started before the feature is built: the problem and the design options first, then the dead ends, then results. A draft in that state is expected; review it for the parts that exist.

When reviewing, look for:

When editing, preserve the voice:

Checklist

Before calling a document done:

Sources