Skip to main content

Developer documentation style guide

This guide covers writing and organizing the public developer docs at dev.writer.com, which Mintlify builds from docs-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 under snippets/, 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:
Every heading is followed by one or two sentences of prose before any list, code block, or table, because a reader arriving from search needs to know what the section holds before the structure starts:
Every page ends with a ## 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:
API reference pages start with what the endpoint does, list required parameters before optional ones, and show realistic requests, responses, and error conditions. Tutorials use numbered steps, include verification steps and troubleshooting for common issues, and end with next steps.

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. 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. Run npx 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:
Wrap code shown in more than one language in <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.
Mintlify’s built-in components (<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, ![](/images/image.png), 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).
For example: ![Architecture of an app that's built with Apps Script](/images/architecture.png), ![User interface showing the login form with username and password fields](/images/login-form.png), ![Flowchart showing the authentication process from login to dashboard](/images/flowchart.png).

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.