Making Your Code Examples Shine - Larry Ullman - Write the Docs Portland 2018

Code examples become genuinely useful—and easier to trust—when they’re built around user needs, enforced through consistent style, and maintained with automation that’s “just enough.” At Stripe, the documentation team treats code snippets as a first-class part of the product experience: they map solutions to what users are trying to accomplish, tailor examples to the languages and skill levels people actually use, and then add enhancements that make copy/paste work reliably.

The process starts with empathy and research, not syntax. Stripe’s documentation strategy begins by identifying which programming languages dominate among customers, then layering in experience level (from junior developers to people using higher-level tools) and the goals behind reading the docs. That research also extends to versioning and frameworks—such as choosing Flask for Python web examples—plus library and API versions. Code examples are shown in the most current versions, while the API reference flags when older versions might differ, because perfectly matching every user’s environment is ideal but expensive.

From there, Stripe focuses on “envisioning enhancements” that reduce friction and prevent confusion. A key improvement is making examples copy/paste-ready with the right credentials and data. When logged in, users see examples containing their own test API keys and test customer IDs; when logged out, they get demo-account equivalents. Stripe also uses interactive “Run” examples (via RunKit) so users can edit parameters like amounts, currency, or even Node version and immediately see results. For cases where real values can’t be prefilled—like Connect platform connected account IDs—placeholders are inserted using a template-style syntax (double curly braces), paired with guidance (mouse-over instructions) explaining what must be replaced before running.

Stripe then applies the same discipline used for written documentation to the code itself. The team maintains a code example style guide covering naming, parameter order, placeholder conventions, comment rules, and language-specific formatting and syntax (including indentation and quotation mark preferences). The style guide also functions as a feedback loop for engineers: code examples communicate what Stripe values—clean, modern best practices—and can reveal inconsistencies across products. Visual presentation matters too; well-formatted snippets can improve readability and break up “walls of text,” making the docs feel simpler and more trustworthy.

Finally, maintaining hundreds of examples across languages requires automation, but not blind cleverness. Stripe uses two complementary approaches: auto-generation on the fly from API reference structure, and a separate manual utility (written in Go) that generates syntactically valid, style-compliant examples from templates. Because correctness can’t be assumed, Stripe tests generated libraries against Stripe Mock (a GitHub project that uses the OpenAPI spec) and is beginning to test code examples as well. Linting and spell-checking help catch small errors, while “pitfalls” to avoid include letting docs and code drift apart and over-automating in ways that create hidden mismatches.

In short: build code examples like user-facing writing, standardize them with a style guide, and keep them accurate through targeted automation and testing—so developers can run what they copy without second-guessing what they’re seeing or whether it will work.