Developer examples and reference

The reader copies the command. This is where an example has to keep its promises.

Give it one useful job, a declared environment and a result the reader can recognize. State the product version, language, prerequisites and starting data. Call it runnable only after checking that combination.

Make the example complete enough

Include the imports, setup, operation and expected result needed for the task. Say where it writes files or changes a document. Use input that a reader can create or obtain, and identify omitted setup explicitly. An ellipsis can abbreviate an explanation; it cannot execute the missing lines.

Preserve identifiers, punctuation and case. Use a fenced block with its language identified. Explain replacements outside the block, and keep typographic quotation marks out of code.

Use fictional account names and reserved example domains. Never publish working credentials. When authentication belongs in the example, use the documented configuration mechanism.

Show the expected result

A file, return value, selection or console output gives the reader something to check. Show output separately from the command and explain variation that affects interpretation. Identify conceptual sketches as pseudocode.

Develop the explanation through an observable change. Instead of “This demonstrates the flexibility of the API,” say what the example changes and how the result can be inspected. If the code returns a new object rather than modifying the original, that distinction belongs in the explanation.

Include the error handling needed to use the operation correctly. Show a relevant failure and recovery without surrounding a small example with an unrelated framework. Do not invent an exception, return field or recovery operation from its plausible name.

Separate command syntax from runnable commands

A syntax summary presents choices; an executable example makes them. Brackets, pipes, braces and ellipses can have real shell effects when copied. Label syntax summaries and explain their notation separately from copyable commands.

Name the shell and environment. Keep prompts and output outside the command block. State a change from a local terminal to a remote session before the next command, when the reader still has time to notice.

Explain each input placeholder: what it represents, where to obtain it and which format it needs. An output placeholder describes a varying result and must not be entered. Use notation appropriate to the destination; angle brackets may become shell redirection.

Structure a reference page

Make the first sentence useful to someone arriving from search or reading a generated member list. Explain what the element does beyond repeating its name. Identify the product and version if the same identifier exists in several APIs.

Present the contract in a predictable order:

1. Name and purpose.
2. Signature or supported syntax.
3. Parameters, including types, units, accepted values, required status and defaults.
4. Return value and side effects.
5. Failure conditions, partial changes and limits.
6. A tested example and relevant related operations.

Keep omission, an empty value and zero distinct when their behavior differs. State which condition makes a Boolean true. For a mutating call, name what changes and when the change becomes visible. Preserve exact class names: write Glyph objects rather than pluralizing the identifier.

Reference writing can be engaging through discovery. A small example can expose a distinction the signature alone hides. Explain that distinction directly; an anecdote between the signature and its parameters usually obstructs lookup.

Review before release

Run the example in the declared environment from a clean starting state. Compare actual output and side effects with the description. Check linked setup instructions and relevant failure behavior.

If the environment is unavailable, record that limit. A syntax check does not establish runtime behavior, and an attractive output block is not a captured result.

Read the prose once more after verification. Keep the detail that explains the result, remove the praise that merely celebrates it, and make the next useful operation easy to find.

As an editing exercise, cover the output block and read only the surrounding prose. Can you predict what will change, what will remain and how to check success? Uncover the actual result and compare. Repair the explanation at the first point where those expectations diverge.

See reference pages for article design and scripts and typography for character and glyph distinctions.