Machine-generated drafts tend to import conventions from other fields and hedge with vague endorsements. These rules catch the patterns that make documentation read as generated rather than written for developers. General term-level guidance lives in word choice.
ai-001 should GuidesAPI docsMarketingBlog Avoid vocabulary that belongs to another field rather than software documentation. Words at home in literary or publishing writing, such as “prose,” read as out of place in developer docs; use the plain term a developer would use, such as “body text.”
Examples
Rationale
Reaching for another field’s vocabulary is a common tell of machine-generated or non-native writing, and it adds friction for a developer audience. Using the field’s own plain terms keeps the register natural.
ai-002 should GuidesAPI docsMarketingBlog Avoid symbols that belong to another field rather than software documentation, such as the section sign (§, also called a silcrow), which is conventional in legal and academic citations. Use plain words or standard documentation formatting instead.
Examples
Rationale
Symbols carried in from other fields, like the legal section sign, look foreign in developer documentation and signal writing that wasn’t produced for this audience. Plain words or standard formatting communicate the same thing without the borrowed convention.
ai-003 should GuidesAPI docsMarketingBlog Don’t use “defensible” as a vague way to say an action is understandable, reasonable, or justified. The word is fine in its literal sense, describing something that can be defended; avoid only the filler usage.
Examples
Rationale
Overusing “defensible” to hedge that an action is reasonable is a recognizable tell of machine-generated writing, and it swaps a specific reason for a vague endorsement. The literal sense stays useful, so only the filler usage is discouraged.