Writing guide
How language is written for each element of a piece, from title to alt text, with limits, voice and one example of each.
One entry per typographic or document element. Each entry gives the place of the element, what a reader uses it for, how long it runs, its voice, and what to write and avoid, with one good and one bad example.
Agents read the same entries as data from src/writing/guide.ts. The rules listed against Lint in each entry are enforced over MDX in content/ by bun run lint:prose.
Voice
- Dry and scientific. A practitioner reporting what a thing does to a capable peer.
- Third person in published pieces: name the platform or the system, or use the passive. Correspondence alone takes "I".
- Verdict or labelled conjecture first, then the mechanism, then the numbers.
- Each number keeps its conditions beside it; each caveat sits beside the claim it limits.
- One hedge on a claim where the uncertainty is real, and none elsewhere.
- Mostly short sentences, with a long one where a mechanism is worked out. Australian English.
- A piece ends on its last fact or its open question, with no line restating the point.
- Irreverence is rationed to one line or one heading in a piece, and stays out of methods and results.
Article
Title
Tells a reader scanning a list which subject this is. First line of a piece, and its name in every index, tab and link.
| Constraint | Value |
|---|---|
| Id | title |
| Level | document |
| Length | up to 60 characters; up to 8 words |
| Person | None |
| Tense | No verb where a name will do |
| Register | A name or a plain noun phrase |
| Lint | length, opens-with-the, first-person, stock-vocabulary |
Do
- Name the subject: a project, an aircraft registration, a method.
- Leave the claim to the deck.
Avoid
- An opening "The".
- Colons and subtitles packed into one line.
- Questions, promises and superlatives.
Good (research/goldray)
Goldray
Bad
The Ultimate Guide to Building a Metal Detector
Opens with "The", promises instead of naming, and could head any piece on the subject. Caught by opens-with-the.
Deck
Lets a reader decide whether to read on, without the body. Directly under the title; also called the standfirst or subtitle.
| Constraint | Value |
|---|---|
| Id | deck |
| Level | document |
| Length | 1 to 3 sentences; up to 60 words |
| Person | Third |
| Tense | Present for what a thing is, past for what happened |
| Register | Dry and concrete; one image at most |
| Lint | length, first-person, stock-vocabulary, leading-label |
Do
- State what the thing is and the result that matters.
- Put the main caveat here if the result depends on it.
Avoid
- Scene-setting about the field or the era.
- Repeating the title.
- Adjectives standing in for a number.
Good (research/goldray)
A metal detector hears one note and forgets it. Goldray is a design for keeping every note, with the place the coil was when it sounded, until a swing becomes a picture of the ground.
Bad
In today's fast-paced world, metal detecting plays a pivotal role for hobbyists everywhere.
Sets a scene, says nothing about this piece, and is built from stock phrases. Caught by stock-vocabulary.
Lede
Gives the finding and its conditions to a reader who stops here. First paragraph of the body, or the hero blurb above it.
| Constraint | Value |
|---|---|
| Id | lede |
| Level | document |
| Length | 2 to 3 sentences; up to 70 words |
| Person | Third |
| Tense | Present |
| Register | Verdict or labelled conjecture first, then the number |
| Lint | length, first-person, stock-vocabulary, leading-label |
Do
- Open on the situation, the number that matters, or a conjecture named as one.
- State what was not done or not measured.
Avoid
- A survey of the field or a definition the reader already has.
- Staged openers and rhetorical questions.
- Detail that belongs in the body.
Good (research/goldray)
Goldray is designed to keep what a metal detector throws away: every measurement, with the place the coil was when it was taken, so that a swing adds up to an image. It comes in five blocks, none of them built, and every depth below is a simulation’s.
Bad
Let's dive into how metal detectors really work, and why everything changes from here.
A staged opener with no fact in it. Caught by stock-vocabulary.
Section heading
Lets a reader find a part of the argument from the contents list. Second-level heading over a run of blocks; listed in the table of contents.
| Constraint | Value |
|---|---|
| Id | section-heading |
| Level | section |
| Length | up to 48 characters; up to 7 words |
| Person | None |
| Tense | Noun phrase; a verb only when the section is an event |
| Register | Plain; one irreverent heading per piece at most |
| Lint | length, opens-with-the, first-person, stock-vocabulary |
Do
- Name what the section contains.
- Keep sibling headings to one grammatical shape.
Avoid
- An opening "The".
- Questions, colons and closing punctuation.
- Headings that only work once the section has been read.
Good (research/vh-mdx)
Nineteen minutes over the Tops
Bad
The night everything changed
Opens with "The" and names a mood where a subject belongs. Caught by opens-with-the.
Sub-heading
Marks a change of subject within a section. Third level and below, inside a section.
| Constraint | Value |
|---|---|
| Id | sub-heading |
| Level | section |
| Length | up to 40 characters; up to 5 words |
| Person | None |
| Tense | Noun phrase |
| Register | Functional; narrower than its section heading |
| Lint | length, opens-with-the, first-person, stock-vocabulary |
Do
- Name the mechanism or the object.
- Use one only when the section has two or more.
Avoid
- An opening "The".
- Restating the section heading.
- Clauses and full sentences.
Good
Kernel lifecycle
Bad
The loop a kernel sits inside
Opens with "The" and describes at length what two words name. Caught by opens-with-the.
Body paragraph
Carries the argument: mechanism, then numbers with their conditions. Text measure of a section, between headings and figures.
| Constraint | Value |
|---|---|
| Id | body |
| Level | block |
| Length | 1 to 6 sentences; up to 120 words |
| Person | Third |
| Tense | Present for how a thing works, past for what was done |
| Register | Dry, scientific, Australian English; mostly short sentences |
| Lint | length, first-person, stock-vocabulary, leading-label |
Do
- Name the platform or the system, or use the passive.
- Give each number its conditions in the same sentence.
- Hedge once, where the uncertainty is real.
- Place a caveat beside the claim it limits.
Avoid
- "We", "our", "us", "I" and "my".
- Stock vocabulary, triads and "not just X, but Y".
- A closing line that restates the paragraph.
- Leading labels in front of a sentence.
Good (research/goldray)
Against a commercial detector, the exposure cap costs about 6 dB, and with no pulse mode it loses to pulse detectors in the worst ground. The cure for the cliff is a ground balance that does not trust the reported height. It has not been written, so the moderate and severe figures stand as the forecast.
Bad
We built Goldray to showcase what a phone can really do. In conclusion, the results speak for themselves.
First person, a stock verb, a template closer, and no number. Caught by first-person.
List item
Presents one of several parallel things for comparison or lookup. One line of a bulleted or numbered list in the body.
| Constraint | Value |
|---|---|
| Id | list-item |
| Level | block |
| Length | up to 30 words |
| Person | Third |
| Tense | Matches its siblings |
| Register | Fragment or one sentence; parallel across the list |
| Lint | length, first-person, stock-vocabulary, leading-label |
Do
- Use a list only when the items are enumerable.
- Start every item with the same part of speech.
Avoid
- An argument broken into bullets.
- A bold label and a colon in front of each item.
- Lists of one or two.
Good (research/goldray)
S5 end-to-end link budget: detection depth by soil
Bad
In short: it works really well in most cases
A leading label in front of a claim with no condition. Caught by leading-label.
Pull quote
Shows a skimming reader the sentence the section turns on. Display line set apart from the body, between paragraphs.
| Constraint | Value |
|---|---|
| Id | pull-quote |
| Level | block |
| Length | 1 to 2 sentences; up to 30 words |
| Short form | up to 14 words; up to 1 sentence |
| Person | Third |
| Tense | As in the sentence it lifts |
| Register | A sentence from the body, or a credited quotation |
| Lint | length, first-person, stock-vocabulary, leading-label |
Do
- Lift a sentence that carries a number or a consequence.
- Credit a quotation, and mark a paraphrase as one.
Avoid
- A line written for effect that the body does not contain.
- More than two in a piece.
- Aphorisms.
Good (research/goldray)
In moderate soil, 5 mm of error in the coil’s height costs a 1 g nugget 16 of its 21 centimetres.
Bad
Sometimes the ground simply does not want to give up what it holds.
An aphorism: no number, no consequence, and nothing the body could support.
Figures and data
Caption
Tells the reader what to see in the figure and what it cannot show. Under or beside a figure, plate, chart or table; includes a figure's title.
| Constraint | Value |
|---|---|
| Id | caption |
| Level | block |
| Length | 1 to 2 sentences; up to 30 words |
| Short form | up to 8 words; up to 48 characters |
| Person | Third |
| Tense | Present |
| Register | Terse; fragments are in order |
| Lint | length, type-label, first-person, stock-vocabulary, leading-label |
Do
- State what the figure shows that the eye would miss.
- Add its standing in a few words: "Not to scale", "Modelled, not printed".
Avoid
- Type labels and numbers: "Figure 3", "Diagram", "Chart".
- An opening "The" in a figure title.
- Repeating the paragraph beside it.
Good (research/goldray)
Five positions along one swing sight the same buried object. Not to scale.
Bad
Figure 3: Diagram of the coil
Numbers the figure and names its type; the reader can see it is a diagram. Caught by type-label.
Stat value
Gives one number to a reader who looks at nothing else. Large figure in a stat row, above its label.
| Constraint | Value |
|---|---|
| Id | stat-value |
| Level | block |
| Length | up to 12 characters |
| Short form | up to 8 characters |
| Person | None |
| Tense | None |
| Register | A number with its unit |
| Lint | length, needs-number |
Do
- Print the number as the body states it, unit included.
- Mark an estimate: "≈6,200 ft".
Avoid
- Words where a number belongs.
- More significant figures than the method supports.
Good (research/goldray)
21 cm
Bad
Much deeper
A comparison with no number and nothing to compare against. Caught by needs-number.
Stat label
Says what the number measures and under which conditions. Small line with a stat value; the condition sits in a second line under it.
| Constraint | Value |
|---|---|
| Id | stat-label |
| Level | block |
| Length | label, up to 24 characters; condition, up to 12 words |
| Short form | up to 14 characters |
| Person | None |
| Tense | None |
| Register | Noun phrase; the condition is a fragment |
| Lint | opens-with-the, first-person, stock-vocabulary |
Do
- Name the quantity in the label.
- Put provenance in the condition: "Predicted, one pass, mild soil".
Avoid
- An opening "The".
- A label that needs the body to decode it.
- Verdicts.
Good (research/goldray)
Depth, 1 g nugget
Bad
The depth it can reach
Opens with "The" and gives no target or condition. Caught by opens-with-the.
Table header
Names what every cell beneath it holds, units included. Top cell of a table column.
| Constraint | Value |
|---|---|
| Id | table-header |
| Level | block |
| Length | up to 24 characters; up to 3 words |
| Person | None |
| Tense | None |
| Register | One to three words; sentence case |
| Lint | length, opens-with-the, first-person, stock-vocabulary |
Do
- Carry the unit in the header, not in each cell.
- Use the term the body uses.
Avoid
- An opening "The".
- Sentences and questions.
- Abbreviations defined nowhere.
Good (research/vh-mdx)
Result
Bad
The outcome of each search effort
Opens with "The" and runs to a clause where one word serves. Caught by opens-with-the.
Table cell
Holds one value for lookup and comparison down a column. Body cell of a table.
| Constraint | Value |
|---|---|
| Id | table-cell |
| Level | block |
| Length | up to 12 words |
| Person | None |
| Tense | Matches its column |
| Register | A value or a fragment; same form down the column |
| Lint | length, first-person, stock-vocabulary, leading-label |
Do
- Keep one fact to a cell.
- Mark a missing value with a dash, and say why below.
Avoid
- Sentences with more than one clause.
- Labels inside the cell.
- Mixed units in one column.
Good
5 cm in moderate soil
Bad
Note: nothing was found during this search
A leading label and a sentence where the value is two words. Caught by leading-label.
Inline and metadata
Alt text
Stands in for the image for a reader who cannot see it. The alt attribute of an image; read aloud, and shown when the image fails.
| Constraint | Value |
|---|---|
| Id | alt-text |
| Level | meta |
| Length | 20 to 150 characters |
| Person | None |
| Tense | Present |
| Register | One plain descriptive sentence |
| Lint | length, alt-missing, alt-preamble |
Do
- Describe what is in the frame, in the order the eye meets it.
- State the content of a chart: the trend and the range.
Avoid
- Announcing the medium: "Image of", "Photo showing".
- Repeating the caption.
- Leaving it empty on an image that carries content.
Good (research/vh-mdx)
Looking up through a dense Antarctic beech canopy, branches and moss-covered trunks closing out the sky.
Bad
Image of trees
Announces the medium and leaves out everything the photograph is there to show. Caught by alt-preamble.
Link text
Tells the reader where the link goes before it is followed. The words of a link, inside a sentence or a source list.
| Constraint | Value |
|---|---|
| Id | link-text |
| Level | inline |
| Length | 1 to 8 words; up to 60 characters |
| Person | None |
| Tense | None |
| Register | The name of the destination |
| Lint | length, generic-link |
Do
- Link the noun that names the destination.
- Use a repository or document name as written at its source.
Avoid
- "Click here", "here", "this link", "read more".
- A bare URL in running prose.
- Whole sentences as links.
Good (research/vh-mdx)
drksci/vh-mdx
Bad
click here
Says nothing out of context, which is how a screen reader lists links. Caught by generic-link.
Summary
Lets a reader outside the site judge the piece from one line. The description in frontmatter: search results, link previews, index cards.
| Constraint | Value |
|---|---|
| Id | summary |
| Level | meta |
| Length | 50 to 160 characters |
| Person | Third |
| Tense | Present |
| Register | One or two plain sentences; the deck, shorter |
| Lint | length, first-person, stock-vocabulary, leading-label |
Do
- Name the subject and the result.
- Write it to survive being cut at 160 characters.
Avoid
- Repeating the title.
- Calls to action.
- Keyword lists.
Good (research/goldray, shortened)
A metal-detecting instrument designed in five blocks. In simulation it finds a 1 g nugget 21 cm down in mild soil. None of it has been built.
Bad
We delve into the fascinating world of metal detecting. Read on to learn more!
First person, a stock verb, a call to action, and no subject or result. Caught by first-person.
Footnote or source
Lets a reader check a claim against where it came from. End matter: a numbered note, or a line in the source list.
| Constraint | Value |
|---|---|
| Id | footnote |
| Level | meta |
| Length | up to 40 words |
| Person | Third |
| Tense | Past for what a source reported |
| Register | Bibliographic; who, what, when, where to find it |
| Lint | length, first-person, stock-vocabulary, leading-label |
Do
- Give author or holder, title, date and a link.
- Pin a repository to a commit or tag.
- Mark a paraphrase as one.
Avoid
- Argument that belongs in the body.
- A source with no date.
- Links with no description.
Good (research/vh-mdx)
Merrilea Price, paraphrased from ABC News, 17 Nov 2026
Bad
Various sources online
Names no author, title or date, so nothing can be checked.
Code comment in an article
Tells the reader why a line is there, which the code cannot say. Inside a code block printed in a piece.
| Constraint | Value |
|---|---|
| Id | code-comment |
| Level | inline |
| Length | line, up to 80 characters; block, up to 2 sentences |
| Person | Imperative |
| Tense | Present |
| Register | Terse; the reason, then the consequence |
| Lint | first-person, stock-vocabulary |
Do
- Give the reason or the constraint.
- Trim the listing to the lines the argument needs.
Avoid
- Restating what the line does.
- Narration addressed to the reader.
- Commented-out code.
Good (research/goldray, adapted)
// Freeze the weights: a canceller left adapting removes targets too.
Bad
// Here we loop over the samples and add each one to the total
Restates the loop beneath it and narrates in the first person. Caught by first-person.
Résumé and letters
Résumé summary
Tells a screener in ten seconds what the person does and at what scale. Top of the résumé, under the name and contact line.
| Constraint | Value |
|---|---|
| Id | resume-summary |
| Level | document |
| Length | 2 to 3 sentences; up to 60 words |
| Person | First, pronoun dropped |
| Tense | Present for the role, past for results |
| Register | Plain; no pronoun, no self-assessment |
| Lint | length, first-person, stock-vocabulary, leading-label |
Do
- State the discipline, the years and one result with its scale.
- Close on the kind of role sought, when the variant is targeted.
Avoid
- Pronouns: "I", "my".
- Self-praise: "passionate", "results-driven", "proven track record".
- A list of tools.
Good
Platform engineer with twelve years in payments infrastructure. Led the move of a card-processing core handling 3 million transactions a day, with no customer-facing outage. Looking for a staff role in reliability.
Bad
I am a passionate, results-driven leader with a proven track record of delivering value.
A pronoun, three self-assessments and no discipline, scale or result. Caught by first-person.
Résumé role bullet
Gives an interviewer one checkable thing that was done and what it moved. Under a role, three to five to a role.
| Constraint | Value |
|---|---|
| Id | resume-bullet |
| Level | block |
| Length | up to 1 sentence; 8 to 28 words |
| Person | First, pronoun dropped |
| Tense | Past; present only in a current role |
| Register | Opens on a verb; one result with a number |
| Lint | length, needs-number, first-person, stock-vocabulary, leading-label |
Do
- Open with what was done, then the number it moved and the scale.
- Name the method when it explains the result.
Avoid
- "Responsible for" and other duties without outcomes.
- Pronouns.
- Two achievements joined in one bullet.
Good
Cut settlement batch time from 4 h to 35 min by moving reconciliation to streaming, across 3 million daily transactions.
Bad
Responsible for various improvements to key systems and processes.
A duty with no action, number or scale; nothing an interviewer could check. Caught by needs-number.
Cover-letter paragraph
Connects one need of the role to one piece of evidence. Body of a cover or concierge letter; two to four to a letter.
| Constraint | Value |
|---|---|
| Id | letter-paragraph |
| Level | block |
| Length | 2 to 4 sentences; up to 80 words |
| Person | First |
| Tense | Present and past |
| Register | Correspondence: plain, direct, one hedge where it is real |
| Lint | length, stock-vocabulary, leading-label |
Do
- Say what the role appears to need, then what was done that matches it.
- Carry one number across from the résumé.
- Greet by name and sign off in a word.
Avoid
- Formal letter furniture and numbered bold headings.
- Enthusiasm with nothing attached to it.
- Retelling the résumé.
Good
I think the role is mostly a migration problem with a reliability deadline attached. I ran one at about the same scale: 3 million transactions a day moved to a new core in nine months, with rollback rehearsed monthly. Happy to walk through what went wrong along the way.
Bad
I am writing to express my keen interest in this exciting opportunity, which aligns perfectly with my passion for innovation.
Could be sent to any employer; no need named and no evidence offered.
Repository
Changelog or PR text
Tells a reviewer what changed, why, and how it was checked. Commit subject and body, pull request description, changelog line.
| Constraint | Value |
|---|---|
| Id | change-text |
| Level | meta |
| Length | subject, up to 72 characters; body, up to 120 words |
| Person | Imperative |
| Tense | Imperative subject; past or present body |
| Register | Plain; fact, cause, then what was verified |
| Lint | stock-vocabulary |
Do
- Open the subject with a verb and name the thing changed.
- Give the reason in the body, and the commands that passed.
- State what was left out or remains unverified.
Avoid
- "Various fixes", "updates", "misc".
- A walk through the diff, file by file.
- Praise for the change.
Good
Add prose lint for MDX under content/
Bad
Updated some stuff and various fixes
Names nothing that changed and gives a reviewer no reason to look.
Lint rules
lengthcounts characters, words or sentences against the limits of the element. Over a hard maximum fails; under a minimum, or over a soft maximum, warns.opens-with-thefails a title, heading, label or figure title whose first word is "The".leading-labelfails a short label glued to the front of a sentence, such as "Note:" or "In short:".first-personfails "we", "our", "us", "I", "my" and "me" outside quotations.stock-vocabularyfails stock AI words, staged openers, chatbot residue, essay-template closers and sales language. A second, weaker list warns.type-labelfails a caption or figure title that only names its type or opens with a numbered type, such as "Figure 3:".generic-linkfails link text that says nothing out of context, such as "click here".alt-missingfails an image with no alt text.alt-preamblefails alt text that opens by announcing an image, such as "Image of".needs-numberfails a stat value or a role bullet with no digit in it.
Code, expressions and blockquotes are never linted, and quoted spans are dropped before a check. Over a hard limit fails; a soft limit, or a length under the minimum, warns.