Skip to Content
drksci
System

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.

ConstraintValue
Idtitle
Leveldocument
Lengthup to 60 characters; up to 8 words
PersonNone
TenseNo verb where a name will do
RegisterA name or a plain noun phrase
Lintlength, 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.

ConstraintValue
Iddeck
Leveldocument
Length1 to 3 sentences; up to 60 words
PersonThird
TensePresent for what a thing is, past for what happened
RegisterDry and concrete; one image at most
Lintlength, 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.

ConstraintValue
Idlede
Leveldocument
Length2 to 3 sentences; up to 70 words
PersonThird
TensePresent
RegisterVerdict or labelled conjecture first, then the number
Lintlength, 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.

ConstraintValue
Idsection-heading
Levelsection
Lengthup to 48 characters; up to 7 words
PersonNone
TenseNoun phrase; a verb only when the section is an event
RegisterPlain; one irreverent heading per piece at most
Lintlength, 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.

ConstraintValue
Idsub-heading
Levelsection
Lengthup to 40 characters; up to 5 words
PersonNone
TenseNoun phrase
RegisterFunctional; narrower than its section heading
Lintlength, 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.

ConstraintValue
Idbody
Levelblock
Length1 to 6 sentences; up to 120 words
PersonThird
TensePresent for how a thing works, past for what was done
RegisterDry, scientific, Australian English; mostly short sentences
Lintlength, 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.

ConstraintValue
Idlist-item
Levelblock
Lengthup to 30 words
PersonThird
TenseMatches its siblings
RegisterFragment or one sentence; parallel across the list
Lintlength, 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.

ConstraintValue
Idpull-quote
Levelblock
Length1 to 2 sentences; up to 30 words
Short formup to 14 words; up to 1 sentence
PersonThird
TenseAs in the sentence it lifts
RegisterA sentence from the body, or a credited quotation
Lintlength, 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.

ConstraintValue
Idcaption
Levelblock
Length1 to 2 sentences; up to 30 words
Short formup to 8 words; up to 48 characters
PersonThird
TensePresent
RegisterTerse; fragments are in order
Lintlength, 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.

ConstraintValue
Idstat-value
Levelblock
Lengthup to 12 characters
Short formup to 8 characters
PersonNone
TenseNone
RegisterA number with its unit
Lintlength, 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.

ConstraintValue
Idstat-label
Levelblock
Lengthlabel, up to 24 characters; condition, up to 12 words
Short formup to 14 characters
PersonNone
TenseNone
RegisterNoun phrase; the condition is a fragment
Lintopens-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.

ConstraintValue
Idtable-header
Levelblock
Lengthup to 24 characters; up to 3 words
PersonNone
TenseNone
RegisterOne to three words; sentence case
Lintlength, 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.

ConstraintValue
Idtable-cell
Levelblock
Lengthup to 12 words
PersonNone
TenseMatches its column
RegisterA value or a fragment; same form down the column
Lintlength, 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.

ConstraintValue
Idalt-text
Levelmeta
Length20 to 150 characters
PersonNone
TensePresent
RegisterOne plain descriptive sentence
Lintlength, 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.

Tells the reader where the link goes before it is followed. The words of a link, inside a sentence or a source list.

ConstraintValue
Idlink-text
Levelinline
Length1 to 8 words; up to 60 characters
PersonNone
TenseNone
RegisterThe name of the destination
Lintlength, 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.

ConstraintValue
Idsummary
Levelmeta
Length50 to 160 characters
PersonThird
TensePresent
RegisterOne or two plain sentences; the deck, shorter
Lintlength, 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.

ConstraintValue
Idfootnote
Levelmeta
Lengthup to 40 words
PersonThird
TensePast for what a source reported
RegisterBibliographic; who, what, when, where to find it
Lintlength, 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.

ConstraintValue
Idcode-comment
Levelinline
Lengthline, up to 80 characters; block, up to 2 sentences
PersonImperative
TensePresent
RegisterTerse; the reason, then the consequence
Lintfirst-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.

ConstraintValue
Idresume-summary
Leveldocument
Length2 to 3 sentences; up to 60 words
PersonFirst, pronoun dropped
TensePresent for the role, past for results
RegisterPlain; no pronoun, no self-assessment
Lintlength, 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.

ConstraintValue
Idresume-bullet
Levelblock
Lengthup to 1 sentence; 8 to 28 words
PersonFirst, pronoun dropped
TensePast; present only in a current role
RegisterOpens on a verb; one result with a number
Lintlength, 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.

ConstraintValue
Idletter-paragraph
Levelblock
Length2 to 4 sentences; up to 80 words
PersonFirst
TensePresent and past
RegisterCorrespondence: plain, direct, one hedge where it is real
Lintlength, 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.

ConstraintValue
Idchange-text
Levelmeta
Lengthsubject, up to 72 characters; body, up to 120 words
PersonImperative
TenseImperative subject; past or present body
RegisterPlain; fact, cause, then what was verified
Lintstock-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

  • length counts 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-the fails a title, heading, label or figure title whose first word is "The".
  • leading-label fails a short label glued to the front of a sentence, such as "Note:" or "In short:".
  • first-person fails "we", "our", "us", "I", "my" and "me" outside quotations.
  • stock-vocabulary fails stock AI words, staged openers, chatbot residue, essay-template closers and sales language. A second, weaker list warns.
  • type-label fails a caption or figure title that only names its type or opens with a numbered type, such as "Figure 3:".
  • generic-link fails link text that says nothing out of context, such as "click here".
  • alt-missing fails an image with no alt text.
  • alt-preamble fails alt text that opens by announcing an image, such as "Image of".
  • needs-number fails 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.

On this page