These rules address characteristics of AI-generated writing that can reduce the quality of developer documentation. They do not attempt to eliminate every pattern associated with generated text. Some of those patterns, including consistent structure and concise phrasing, are also desirable characteristics of documentation.
Developer documentation is highly structured, consistent, and concise by design. AI-generated writing often shares these characteristics but can also import language and conventions from business, marketing, academic writing, and engineering specifications. The result can include jargon, business slang such as the ask and the tell, and overly complex descriptions that are inappropriate for developer documentation.
These rules, together with related guidance elsewhere in the style guide and the word list, help identify and remove those characteristics while preserving the conventions that make developer documentation clear and useful.
ai-001 should GuidesAPI docsMarketingBlog Use vocabulary that is familiar in software and hardware developer documentation. Replace literary, publishing, or linguistics terms with plain equivalents, such as body text for prose, tone for register, and word choice for diction.
Examples
Rationale
Vocabulary from another field makes developers interpret an unfamiliar term before they can act on the content. Familiar developer terms state the same idea directly.
ai-002 should GuidesAPI docsMarketingBlog Use symbols that are familiar in developer documentation. For example, replace the section sign (§), which is used in legal and academic citations, with a section name or link.
Examples
Rationale
An unfamiliar symbol makes readers identify a convention from another field before they can follow the reference. A section name or link identifies the destination directly.
ai-003 should GuidesAPI docsMarketingBlog Don’t use defensible as a general sign of approval. State why a choice is reasonable. Use defensible only when you mean that a choice or position can be defended.
Examples
Rationale
Calling a choice defensible does not explain why the choice works. Give the reason so the reader can evaluate it.
ai-005 should GuidesAPI docsMarketingBlog Don’t use hedge, hedging, or hedged as general editorial labels. Name the effect instead: the wording qualifies a claim, avoids a commitment, or gives an approximate count. Keep hedge for its financial sense.
Examples
Rationale
As an editorial label, hedge is jargon many readers don’t share, and it is a recognizable sign of AI-generated text. Naming the actual behavior is more direct and easier to comprehend.
ai-006 should GuidesAPI docsMarketingBlog 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. For example, robust is precise in robust estimator, and showcase can name a gallery of sample apps. Check the word list for each term’s verdict and replacements.
Examples
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.
ai-007 should GuidesAPI docsMarketingBlog Use is, are, and has when they state the fact directly. Don’t replace them with serves as, stands as, functions as, features, or boasts. Keep represents for object-oriented and data contexts, where an object represents a record.
Examples
Rationale
Generated text often avoids is and are to sound more engaging, and the substitutes add words without adding meaning. A direct description of a concept increases comprehension and improves translation.
ai-008 should GuidesAPI docsMarketingBlog State the point directly. Don’t introduce it by rejecting a claim that the content hasn’t made, such as it’s not just X, it’s Y or this isn’t about X, it’s about Y. Use not only X but also Y only when both points matter. Compare real alternatives directly with rather than or instead of.
Examples
Rationale
Generated text often opens a sentence with a claim it then rejects, so that the real point arrives as a correction. Rejecting an unstated claim creates a disagreement the reader did not have and delays the point. Compare alternatives only when the distinction helps the reader choose.
ai-009 should GuidesAPI docsMarketingBlog Include an item only when it adds distinct information. Don’t add an adjective, benefit, or list item only to increase the number of items.
Examples
Rationale
Generated text often adds a vague third item to complete a group of three. The extra item makes the reader look for a distinction that is not there.
punct-028 should word-003 should word-001 should clarity-010 should clarity-011 should claim-002 should claim-003 should skim-002 should skim-003 should clarity-002 should clarity-003 should voice-010 should ai-004 (retired 2026-09-10): “Avoid em dashes.” It restated punct-028, which
holds the rule for every content type. Its editing guidance (rewrite the
sentence rather than replace each dash) and its example pair moved into
punct-028. Rules that span topics are not duplicated; this page lists
punct-028 under “Applicable rules from other topics” instead. The ID stays
reserved and is never reused.