Developer documentation style guide
This guide covers writing and organizing the public developer docs at dev.writer.com, which Mintlify builds fromdocs-official/. How to edit, add pages to docs.json, and preview locally is in
docs/development/developer-docs.md. Marketing and product writing follow WRITER’s
general style guide instead.
Google’s developer documentation style guide is the base reference. Where
this guide is silent, follow Google; where they differ, this guide wins.
Write for a developer solving one problem
Developers come to the docs to implement a feature or fix an error. They search, scan for the relevant part, and jump between sections; few read a page top to bottom. So every page either helps the reader finish a task or explains why that task matters, and its structure gets them to the answer fast. Organize around what developers do, not around product features, with one problem per heading. Put the most common answer or code example at the top of its section and background theory after it. Start with the smallest working example, then add complexity in steps (configuration, options, advanced features), each building on the last. Document the common, successful path first, with verification steps (“You should see…”) so readers know they’re on track; edge cases and troubleshooting come after it, not instead of it. Keep sections short, and use code blocks, lists, bold text, and quick-reference tables for parameters and error codes to break up walls of text. Keep what a task needs on one page, with parameter descriptions next to the code that uses them, so readers don’t bounce between concept pages and the API reference. Cross-link related pages for readers who land on the wrong one. Content that appears on several pages belongs in a snippet undersnippets/, so a change lands everywhere at once.
Write as if every feature has always existed. “New”, “recently”, “as of [date]”, and “latest version” date the page
the moment it ships, so keep time references to changelog entries and deprecation notices: “This feature
provides…”, not “As of November 2025, this feature is available…”; “The API endpoint…”, not “The new API
endpoint…”.
Page pattern
Every page opens by saying what the reader will accomplish and why it matters:## Next steps section linking follow-up tutorials, related features, and advanced
configuration where it applies. It is the one heading that stays a noun phrase, so readers find it in the same
place on every page:
Voice
Address the reader as “you”, in active voice and present tense, with direct imperatives: “Install the SDK”, not “You need to install the SDK” or “You will install the SDK”.
For example, not “Our powerful API makes it easy to integrate authentication. We’ve designed a simple system that
will help you get started quickly.” but “The authentication API handles user login and token management. Follow these
steps to integrate authentication into your application.” Not “You need to install the WRITER SDK before you can
start building.” but “Install the WRITER SDK before building your application.”
Mechanics
- Use the Oxford comma in lists.
- Spell out zero through nine and use numerals for 10 and up, except where that would mix the two in one phrase: “there are 2 people and 15 dogs”. Spell out a number that starts a sentence.
- No periods in acronyms: UK, not U.K.
- Write “generative AI”, not “GenAI” or “gen AI”.
Headings
Headings use sentence case (capitalize the first word and proper nouns) and start with an imperative verb that says what the reader does, because that matches how people search and tells them what the section gets them. Avoid gerunds (“Configuring”), noun phrases (“Configuration”, “Overview”), questions (“How do I configure X?”), and passive constructions (“Getting started”).Next steps is the one exception, above.
Links
Link text says where the link goes (“Learn more about authentication methods”), never “click here”, “read more”, or “this link”, and external links get a sentence of context. Runnpx mint broken-links from docs-official/ before
publishing; .github/workflows/docs-official-checks.yml runs it and mint validate on every PR that touches the
folder.
Code examples
Readers paste examples straight into their own code, so every example runs as-is: all imports, dependencies, and setup, the complete request and response, error handling where a real integration needs it, and realistic names, values, and scenarios instead of foo/bar placeholders. Comment only the non-obvious lines. When common variations exist, show more than one example. Test each example as written, in every language it’s shown in, before publishing. API and SDK examples include the full client initialization:<CodeGroup>: API endpoint examples in cURL, Python, and JavaScript,
and SDK examples in Python and JavaScript where both exist. A standalone JSON example needs no <CodeGroup>. Writer
Framework pages (framework/) and Agent Builder pages are the exception to both rules: their code runs on the
Framework or on the reader’s own deployed app, not on the SDK, and Framework code is Python-only.
<CodeGroup>, <Steps>, <Card>, <Note>, <Warning>, <Tip> and the rest)
are available in every MDX file without an import. Only snippets are imported, then used as components:
Images and alt text
Alt text replaces the image when it isn’t visible, so swapping every image for its alt text should leave the page’s meaning unchanged. Describe what the image does on the page, not only what it shows. Informative images (information the text doesn’t carry), functional images (buttons, links), and complex images (charts, diagrams, screenshots that need describing) get alt text. Leave it empty,, so
screen readers skip the image, when the image is decorative, repeats what the surrounding text already says, or is a
UI screenshot, icon, or visual aid for content already in the text.
Good alt text:
- stays under 155 characters, as a full sentence or noun phrase with punctuation for natural pauses;
- leaves out “Image of” and “Photo of”;
- avoids all caps, which screen readers may read letter by letter;
- stays the same for an image that repeats (controls, status indicators, icons).
,
,
.
Before you submit
Check that the page:- opens with what the reader will accomplish and why;
- has prose under every heading, sentence-case imperative headings, and ends with
## Next steps; - uses active voice, present tense, “you”, and direct imperatives, with no qualifiers, marketing language, or “we”;
- has complete, tested examples;
- passes
npx mint broken-links.