Writing Code Sample Explanations
Practice writing explanatory text around code samples in technical documentation.
Code sample documentation conventions
- Intro phrase: "The following example shows how to..."
- Inline comments: "Replace X with your actual Y" and "The response will contain..."
- Callouts: Note / Tip / Warning — specific, actionable, with consequences
- Placeholders: ALL_CAPS names matching the code block exactly
- Copy-paste-ready: complete, runnable code with no ellipsis gaps
Question 0 of 5
Which sentence best introduces a code sample in API documentation?
"The following example shows..." is the standard introductory phrase for code samples. The sentence does four things:
- Sets the action: "create a new user" — tells the reader what the code achieves before they read it.
- Names the method and path:
POST /users— gives the technical anchor. - States the mechanism: "with the required fields in the request body" — tells the reader what to pay attention to.
- Leads naturally into the code block without being abrupt.
Which inline comment style is most appropriate for code samples in API documentation?
Documentation inline comments guide the reader, not the original developer. Best practices:
- "Replace X with..." — instructs the reader to substitute a placeholder value. This is the most common and important pattern in doc code samples.
- "The response will contain..." — previews what the reader should expect next, connecting the code to the narrative.
- Comments should be short and instructional, not explanatory of obvious code.
YOUR_API_KEY — the reader needs to know what to substitute. Option C uses developer-draft language that should never appear in published docs. Option D over-explains what the code statement is, which is patronising and adds noise.Which callout is written most effectively in API documentation?
A "Note:" callout must give the reader a complete, actionable piece of information — not a vague alert.
- Specific value: "3,600 seconds (1 hour)" — both machine-precise and human-readable.
- Consequence stated: explains what happens if ignored ("interrupted access").
- Resolution included: "request a new token using the refresh token" — tells the developer exactly what to do.
- Note: supplemental information the reader should be aware of.
- Tip: a recommendation or shortcut that improves the experience.
- Warning: a potential problem that could cause data loss, security issues, or breaking errors.
- Caution: something that could cause unintended or irreversible results.
Which instruction phrase is the standard way to tell readers to substitute a placeholder in a code sample?
"Replace X with your actual Y" is the canonical placeholder instruction in technical documentation.
- "Replace" — imperative verb, unambiguous action.
- Exact placeholder name —
YOUR_API_KEYin code font matches what appears in the sample, so the reader can find it immediately. - "your actual" — signals this is a real value the reader must supply, not a literal string to type.
- Source location — "from the dashboard" tells the reader where to get the value.
YOUR_PROJECT_ID with your project ID", "Replace REGION with your AWS region (e.g., us-east-1)". The consistency matters — readers learn to scan for this phrase when working through a new doc.Which convention makes a code block copy-paste-ready in API documentation?
Copy-paste-ready code blocks follow three conventions:
- ALL_CAPS placeholders —
YOUR_API_KEY,YOUR_PROJECT_ID. These are visually distinct, easy to find-and-replace, and are the universal convention readers expect. - Complete, runnable code — no
...gaps that require guessing. The reader should be able to copy the block, make the substitutions, and run it immediately. - Full command — include the HTTP method, base URL, headers, and body. A curl example that omits the
-H "Content-Type: application/json"header will fail silently for many readers.
... is acceptable only for long output samples where the full content is irrelevant, never for input/request code.