Formatting Code Samples in Documentation: Indentation, Consistency, and Readable Blocks
Code samples are the most scrutinised part of technical documentation, and their formatting is not a cosmetic afterthought — it is a signal of whether the whole document can be trusted. A reader who sees inconsistent indentation, tabs mixed with spaces, or a sample that does not run assumes, reasonably, that the prose is equally careless. Formatting decisions that seem trivial in isolation compound into the difference between documentation developers rely on and documentation they route around.
This guide covers how to format code in documentation deliberately: choosing an indentation style, enforcing it, and making code blocks readable and reliable. It complements the process in our docs-as-code workflow guide; if you are new to the craft, ground yourself first in our beginner's guide to technical writing. For the underlying language conventions, Google's public code style guides are an authoritative reference across many languages.
Why Code Formatting Is a Documentation Decision
When you put code in documentation, you are making an editorial choice, not just pasting from an editor. The sample teaches by example — readers copy not only the logic but the style, so sloppy formatting propagates into their codebase. It also has to be readable in a context different from an IDE: narrower columns, no code folding, often on mobile. And it must survive copy-paste intact, which means invisible characters, smart quotes, and mixed whitespace become real bugs the moment a reader pastes them. Treating formatting as a documentation decision — governed by your style guide, not by whatever your editor happened to produce — is what separates professional docs from a wall of pasted snippets.
Choosing and Enforcing an Indentation Style
The tabs-versus-spaces debate is famous, but in documentation the answer is pragmatic: follow the dominant convention of the language you are documenting. Python's PEP 8 mandates four spaces; Go uses tabs and ships gofmt to enforce them; many JavaScript projects use two spaces via Prettier. Match the ecosystem your readers live in, because a Python sample indented with tabs looks wrong to every Python developer and, worse, can actually break in Python where indentation is syntactic. Whatever you choose, the non-negotiable rule is to never mix tabs and spaces within a sample — mixed whitespace is invisible on screen but produces errors that baffle readers when they paste. Pick per-language, document the choice, and enforce it mechanically rather than by eye.
Consistency Across Every Sample
Individual samples matter less than the consistency between them. A reader moving through your docs should never have to re-orient because one page uses two-space indentation and camelCase while the next uses four spaces and snake_case. Consistency covers indentation width, naming conventions in your placeholder values, quote style, how you show command prompts, and how you represent values the reader must replace (pick one convention — angle brackets like <your-api-key> or ALL_CAPS placeholders — and use it everywhere). This uniformity is invisible when present but constantly distracting when absent, and it is exactly the kind of thing a project style guide exists to settle so no individual writer has to decide twice.
Make Code Blocks Readable
Beyond indentation, several choices govern whether a code block is genuinely readable. Use fenced code blocks with a language identifier so your renderer applies syntax highlighting — colour dramatically improves scan-ability and helps readers parse structure. Keep line length short enough to avoid horizontal scrolling, which is punishing on mobile; break long lines at sensible points. Show just enough context for the sample to make sense — a bare one-liner with no surrounding function can be as confusing as an entire file. And render code as real, selectable text, never as a screenshot: screenshots cannot be copied, cannot be read by screen readers, and cannot be searched, making them one of the worst anti-patterns in technical documentation.
Annotate Without Breaking Copy-Paste
Readers need explanation, but explanation must not sabotage the sample's usability. The tension: inline comments teach, but if you add ellipses, line numbers baked into the text, or a shell prompt character ($) inside the code, a reader who copies the block gets something that will not run. Best practice is to keep the code block itself pure and copy-paste-clean, and put explanation in real code comments (which are valid in the language) or in prose and callouts around the block. Some documentation platforms support annotated code with markers that render as clickable notes but are stripped from the copied text — the best of both worlds. If you show terminal sessions, separate the command from its output so readers can copy the command alone.
Automate Formatting and Verification
The only reliable way to keep code samples consistent and correct at scale is to stop relying on human diligence. Run every sample through the language's canonical formatter — Prettier, Black, gofmt, rustfmt — before it enters the docs, so formatting is uniform by construction. Better still, extract code samples and run them in your CI pipeline so a sample that no longer compiles fails the build, catching the drift that manual review always eventually misses. This turns "we try to keep samples updated" into a guarantee. To operationalise all of this, our Code Sample Style Checklist template captures the per-language conventions and the copy-paste rules on one page, and the Darlo Technical Writing course on documenting code walks through building an automated sample-testing pipeline. Explore it at /courses, and quality-gate your pages with our pre-publish review checklist.
Code Sample Style Checklist
A one-page reference of per-language indentation conventions, placeholder and prompt formatting rules, and copy-paste-safety checks to keep every code block in your docs consistent and runnable.
Tabs or spaces in documentation code samples?
Follow the dominant convention of the language you are documenting: four spaces for Python (PEP 8), tabs for Go (enforced by gofmt), two spaces for many JavaScript projects. Matching the ecosystem your readers live in matters more than any universal rule — and never mix tabs and spaces within a single sample.
Why shouldn't I use screenshots of code?
Screenshots cannot be copied, cannot be read by screen readers, cannot be searched, and often render at illegible sizes on mobile. Always use real, selectable text in fenced code blocks with a language identifier so readers get syntax highlighting and can copy the code reliably.
How do I keep code samples from becoming outdated?
Run every sample through the language's canonical formatter (Black, Prettier, gofmt) for consistency, and extract and execute samples in your CI pipeline so any that no longer compile fail the build. Automated verification turns "we try to keep them updated" into an enforced guarantee.