Code Samples

A sample is read by someone about to run it. Show what they should type, show what they should expect back, and leave out everything they would have to undo.

Intros

Introduce a sample with a complete sentence ending in a colon, saying what the sample does rather than that it exists:

Recommended: Compare the vendored copy against what upstream serves:

Not recommended: Example:

Not recommended: Run the following command:

The second says nothing the reader cannot see. The third describes the shape of the page instead of the work.

Where the sample is the object of the introducing sentence, no colon is needed and none should be added:

Recommended: The queue is triggered by applying the 🚀 Status: Commit Queue label.

Show the command, not the ceremony

Give the shortest sample that actually works. Leave out flags that repeat a default, directory changes the reader does not need, and output that carries no information.

Recommended: pnpm install

Not recommended: cd ~/projects && pnpm install --silent=false

Every line the reader has to skip is a line they might instead run.

Prompts

A shell prompt marks which lines are typed and which are output. Which lines carry a $ is settled by Documenting Command-Line Syntax, which owns that rule: every line of a multi-line input, optional on a lone command, and consistent across a page that mixes the two.

Nothing here argues with that, because on this site the prompt costs the reader nothing. It is set in a <span class="prompt"> styled user-select: none, so selecting the line copies the command and leaves the $ behind. Where a prompt cannot be marked up that way, a reader who has to strip it after pasting is better served without it.

Never show a root prompt (#) for something that does not need root.

Placeholders and long lines

Set a value the reader supplies in a <var> element and say what belongs there — see Explaining placeholders.

Keep lines short enough not to wrap. A wrapped command reads as two commands, and the reader cannot tell where the break was ours and where it was theirs. If a command genuinely cannot fit, break it at a point the shell accepts and say so in the sentence above it.

For the notation used to show optional and repeated arguments, see Documenting Command-Line Syntax.