Style guide rule global-003, Avoid idioms and slang, shown as a rule card with its severity and examples, and as a JSON object

Developer Experience style guide

Structured rules for writing developer documentation, for people and AI agents. Every rule has an ID, a severity, rationale, and examples, so you can track and process rules with the same precision as other objects in code.

Read the style guide About StyleOps

Overview

Documentation rules for hardware and software development

The Developer Experience style guide is a free style guide for writing developer documentation. It covers technical documentation for hardware and software development, and related tools, platforms, standards, interfaces, and programming languages. It is licensed under CC BY-SA 4.0, so you can use and even adapt it for your own projects with attribution.

The style guide is also built into the StyleOps documentation tool, which reviews and generates developer documentation.

Principles and format

Structured editorial decisions, in a format you can cite

The style guide is uniquely structured for quick reference, citation, and LLM processing instead of using an article-based format. The editorial decisions are stored as numbered rules, so that you can cite them in documentation reviews, and so that your documentation has one voice no matter who, or what, wrote it.

Principles

People first, machines second

Writing standards that improve human technical writing, while targeting the more problematic AI writing habits.
Scannable and concise

Organization, phrase, and sentence patterns that prioritize search, visual scanning, and quick comprehension.
Global and accessible

Wording that translates cleanly and works well with assistive technology.
Clarity over purity

Prioritizes clear grammatical structure over traditional but awkward structure.
Docs as a discipline

Developer documentation has its own conventions, distinct from general technical writing, marketing, and academic writing.
Decisiveness over endless caveats

Decisive rules instead of endless exceptions. The guide is often stricter and more opinionated than other industry style guides.

Format

Sections

Audience, grammar, punctuation, formatting, organization, multimedia, code, trust, API docs, and terms.

11
Rules

Include a heading, rule ID, description, severity, content types, rationale, and a set of examples.
Rule IDs

A topic prefix and a number, such as punct-028. IDs are stable and never reused, so rule citations stay valid.

punct-028
Severity

Indicates whether a rule is required, strongly recommended, or a permitted variation that is never enforced.

must, should, may
Applies to

The content types a rule applies to: guides, API docs, marketing pages, or blog posts.

4 types
Rationale

The reason behind each rule, for deciding edge cases and judging whether an override is justified.

API reference

Detailed guidance for API reference docs

The API reference documentation rules cover the most common API elements, from API deprecation notices to return values. API reference documentation requires dedicated guidance because it is structurally different from developer guides and is displayed directly in tooltips in coding tools, so the recommended writing styles must reflect that.

docs.developerexperience.com/style-guide/api-documentation/members-parameters/

Developer Experience Docs

Style guide API documentation Members and parameters

Members and parameters

Spell out both boolean values

api-param-004 should API docs

For boolean parameters and properties, describe what happens when the value is true and when it is false. If either description is long, use a separate sentence for each value. Write the literals in code font, spelled as the language spells them (true, True, TRUE). A sentence can open with a lowercase literal in code font; if your group prefers not to, write around it by opening with If or Returns. When true and false are ordinary words rather than the values (a true copy), code font isn't required.

Examples

recursive: If true, deletes subdirectories too; if false, deletes only files in the top-level directory.
recursive: Whether the delete is recursive.
verbose (Python): True to log every request; False to log errors only.

Rationale

A boolean's meaning is not obvious from its name, so stating what each value does keeps the reader from guessing which way is which. Code font marks true as the value the caller passes, which is why it also carries the language's own spelling; the word true in ordinary text stays a word.

On this page

Read the members and parameters rules

AI language

Avoid specific AI-generated writing issues

The style guide includes rules that target the specific AI-generated writing habits that make documentation verbose and harder to comprehend.

docs.developerexperience.com/style-guide/audience/ai-language/

Developer Experience Docs

Style guide Audience AI language

AI language

Replace decorative words

ai-006 should Guides API docs Marketing Blog

Replace decorative words that make a specific fact vague, such as delve, tapestry, seamless, foster, and pivotal. State the fact in plain words. Keep a word when its technical or literal sense is precise.

Examples

The SDK retries failed requests three times before it raises an error.
The SDK delves into robust retry handling, fostering seamless recovery from failures.

Rationale

Generated writing can overuse decorative vocabulary. In documentation, decorative words can replace a specific fact with a vague impression. Keep literal and technical uses that state the meaning precisely.

On this page

Read the AI language rules

Globalization

Documentation for a global audience

The included globalization rules optimize content for more accurate machine translation and cultural considerations, which reduces tech debt and localization expenses.

docs.developerexperience.com/style-guide/audience/globalization/

Developer Experience Docs

Style guide Audience Globalization

Globalization

Avoid culture-specific references

global-005 should Guides API docs Marketing

Avoid references that depend on knowledge of a particular culture, including holidays, sports, traditions, and regional practices.

Examples

Traffic doubles during the November promotion.
Traffic doubles during the Thanksgiving promotion.

Rationale

Readers might not recognize particular holidays, sports, traditions, or regional practices, and translators might not have an equivalent reference. Name the date, event, or behavior that matters.

On this page

Read the globalization rules