Overview

The Developer Experience style guide covers technical documentation for hardware and software development, and for the related fields that document the use and development of hardware and software platforms, interfaces, and programming languages. Within that scope, it covers developer guides, tutorials, README files, API reference documentation, and the developer-facing text around them.

The guide is written for developers, engineers, technical writers, and technical editors, and for the AI agents and large language models that draft and review documentation alongside them. It records editorial decisions so that you don’t have to repeat them, and so that your documentation has one voice no matter who wrote it.

Principles

Every rule in the guide follows from a few priorities:

• People first, machines second. Text has to be quick for a person to process. It should also be structured enough for tools and models to consume, but never at the reader’s expense.
• Scannable and concise. Readers scan developer documentation to find an answer. Standard phrase and sentence patterns, drawn from user research on how developers read documentation, make that scanning fast.
• Global and accessible. The rules favor wording that translates cleanly and works well with assistive technology.
• Clarity over grammatical purity. When the grammatically correct construction is awkward, the guide chooses the clear one.
• Friendly, but brief. The tone is conversational, with conciseness and quick comprehension taking priority over warmth.
• Developer documentation is its own discipline. Its conventions differ from general technical writing, marketing, and academic writing, and the rules treat it that way.
• Clear rules over lists of caveats. The guide is often stricter and more opinionated than other industry style guides.

Format

The guide presents its rules and terms in a consistent format. Knowing the parts makes it faster to find a rule, judge how firmly it applies, and cite it.

• Sections and topics. The guide is divided into sections, such as Audience, Grammar, and Punctuation, and each section into topic pages. A section’s landing page holds guidance that applies across the section and small rules that don’t need a page of their own. Each topic page opens with a short overview, followed by its rules, one per heading.
• Rules. A rule appears as a card under a heading that summarizes it. The card shows the rule’s ID, its severity, and the content types it applies to, followed by the decision itself in one or a few sentences. Examples and a rationale follow the card.
• Rule IDs. Every rule has an ID, such as punct-028, made of a prefix that names the topic and a three-digit number. IDs are stable. A rule keeps its ID when its wording changes, and a retired ID is never reused. The number is only an identifier and says nothing about importance or order. Use the ID to cite a rule or to link to it (the ID on each card links to the rule’s anchor).
• Severity. Each rule is marked must, should, or may. A must rule is required, and breaking it is an error. A should rule is a strong recommendation, and you break it only with a reason. A may rule describes a permitted variation and is never enforced.
• Applies to. The content types a rule is in force for. Guides means developer guides, tutorials, and README files. API docs means API reference documentation. Marketing means a developer landing page or a documentation page on a marketing site, which can carry some marketing, blog, or community content. The guide doesn’t cover marketing websites as a whole. Blog means blog posts. A rule applies only to the types it lists, so a rule marked API docs alone doesn’t apply to guides. Most rules apply to guides, API docs, and marketing pages, and about half also apply to blog posts.
• Examples. Most rules include examples. A check mark (✓) marks text that follows the rule, and a cross (✗) marks text that breaks it.
• Rationale. The reason behind a rule. Read it to decide the edge cases the rule doesn’t spell out, and to judge whether an override is justified.
• Applicable rules from other topics. A rule lives in exactly one topic. When it also matters to another topic, that page lists it at the end under this heading, with a link to the rule in its home topic, so nothing is stated twice.
• Deprecated rules. When a rule is retired, its page lists the ID, the retirement date, and what replaced it, at the end of the page under this heading. The ID stays reserved.
• Word-list verdicts. Each entry in the word list opens with a verdict. Avoid means don’t use the term. Prefer means use this term over its variants. Restricted means use it only in the sense the entry describes. Acceptable means the term is fine and unenforced. Style records a spelling or capitalization preference. Where relevant, an entry also gives the term’s grammatical form, its canonical spelling, the variant forms it supersedes, and replacements to use instead of an avoided term.

Sources and status

The rules come directly from technical writers who specialize in developer documentation, from user research studies on how developers use documentation, and from experience using and contributing to the documentation style guides of the industry’s largest technology companies.

This is the guide’s first release, so we are adding new rules often during its first six months.

Precedence and fallback

When style guidance conflicts, apply it in this order:

1. Project-specific style. A product or project may document deliberate exceptions; those win within that project.
2. This guide. The rules here override any external reference where they conflict.
3. The Chicago Manual of Style (17th edition or current) for general English style this guide doesn’t address: grammar, punctuation, typography, capitalization of common forms, citation style. Chicago is the authoritative external reference; on questions this guide is silent about, Chicago is the authority.
4. Merriam-Webster for spelling and hyphenation of words the word list doesn’t cover.

The word list

The word list records per-term verdicts: which terms to avoid, which to prefer, which are restricted to one sense, and how to spell and case the rest. Each entry carries a rationale. When a question is about a specific word rather than a construction, check the word list before the grammar and punctuation sections.