Writing Style
Language conventions, tone guidelines, and rhetorical approaches that shape how API documentation communicates with its audience. This section covers grammar distinctions, content strategy principles, and stylistic choices that affect clarity, professionalism, and user engagement in technical writing.
Example Audience Communication Workflow:
active voice
Definition: grammatical sentence structure where the subject performs the action rather than receiving it
Purpose: creates direct, clear communication that emphasizes who does what in API documentation
Example:
- ✅ Active - "The API returns a JSON response"
- ❌ Passive - "A JSON response is returned by the API"
Related Terms: rhetorical approach, tone, voice
Source: API Docs Glossary: Style Guide
affect vs effect
Definition: commonly confused words where "affect" typically functions as a verb meaning "to influence" and "effect" typically functions as a noun meaning "the result"
Purpose: maintains professional credibility and clarity in technical writing by using correct grammar
Examples:
- verb - "API latency affects user experience"
- noun - "The effect of caching improves response time"
Sources:
- I'd Rather Be Writing: "How do design, length, and relevance affect how people use API reference docs -- interview with Bob Watson"
- Wordrake: "Affect vs. Effect: Understanding the Difference and Choosing the Right Word" by Ivy B.Grey
banner blindness
Definition: also known as ad blindness and/or banner noise; cognitive phenomenon where readers automatically filter out and ignore page elements that resemble advertisements or interruptive UI patterns — banners, callout boxes, and mid-content CTAs — regardless of their actual content or relevance
Purpose: explains why interruptive UI elements placed within documentation — download CTAs, promotional banners, large callout boxes — often fail to achieve their intended goal and may actively reduce reader trust; readers trained by ad-heavy web experiences apply the same filtering behavior to docs, making visual prominence a poor proxy for reader attention; understanding banner blindness helps writers advocate for content placement decisions grounded in reader behavior rather than assumed visibility
Why this belongs in Writing Style: describes a perceptual
and rhetorical constraint that operates at the content design and
page level — directly shaping decisions about how to present
warnings, callouts, and CTAs so they are actually perceived;
most actionable as a writing and layout concern rather than a
strategic or organizational framework; Frameworks & Strategy
covers meta-level planning models, while banner blindness
is a bias writers write and design against element by element
banner blindness vs docs theater
| Banner Blindness | Docs Theater | |
|---|---|---|
| Mechanism | Readers filter elements that look like ads or interruptions | Writers produce elements that perform thoroughness without delivering substance |
| Problem Origin | Reader behavior shaped by web conventions | Writer or organizational incentives |
| Result | Important content goes unseen | Present but untrustworthy content |
| Overlap | Banners used for docs theater are doubly ineffective | Performing thoroughness to an audience that has already stopped looking |
Example: a team adds a large mid-page CTA banner linking to a product download on several user manual pages, reasoning that high-traffic doc pages are good real estate for driving downloads; in practice, readers already using the manual likely have the product — and readers who don't have trained themselves to scroll past anything that resembles an ad banner; placing a download link in the page chrome — global header, footer, or navigation — reaches the same audience without interrupting the task that brought them to the page; if the CTA is implemented, tailoring it to page context such as - "want to try this specific feature? Sign up for a free trial" - may reduce the generic ad signal
Related Terms: accessibility, CTA, docs theater, DX, progressive disclosure, rhetorical approach, Seven-Action Documentation Model, UI, UX
Sources:
- Wikipedia: "Banner blindness"
- Write the Docs #general channel discussion, March 2026
Clayton's Docs
Definition: rhetorical and communicative failure mode; documentation that exists in place of real docs — "the docs you have when you don't have any docs"; a substitute that fulfills the formal requirement of having docs without delivering its substance or value
Purpose: names the gap between docs' existence and its usefulness; helps teams recognize when placeholder, generated, or inherited content is being treated as a genuine docs investment, and why that distinction matters for reader trust and product quality
Why this belongs in Writing Style: describes a failure of
intent and substance rather than a tool, workflow, or architectural
pattern; fundamentally about the relationship between form and
genuine communicative value
Clayton's Docs vs related terms
| Term | Description | Distinction from Clayton's Docs |
|---|---|---|
| Ersatz Docs | substitute docs — same phenomenon, different tradition; uses the German loanword for substitute goods | regional synonym; Clayton's Docs draws on Australian and New Zealand vernacular, Ersatz Docs is more internationally accessible — choose based on audience and apply consistently |
| docs theater | active performance of quality docs — someone is creating the appearance of substance | docs theatre involves intent; Clayton's Docs is more neutral — the failure mode is absence masquerading as presence, not performance for its own sake |
| docs rot | content that was once accurate and has since decayed through model collapse, content plateaus, or staleness | docs rot describes substance that existed and degraded; Clayton's Docs describes content that never had genuine substance to begin with |
Example: an AI-generated wiki that appears to cover an entire codebase — complete with diagrams and navigation — but delivers output that a team treats as a documentation solution rather than a starting point; or a README written because every repo must have one, not because anyone considered what a reader would need
Related Terms: AI-assisted documentation, docs-as-code, docs-as-ecosystem, docs-as-tests, docs theater
Sources:
- passo.uno: "Code wikis are documentation theater as a service" by Fabrizio Ferri Benedetti
- Wikipedia: "Claytons"
- Write the Docs #ai channel discussion, March 2026
content
Definition: technical communication concept; anything written for someone else to read, encompassing documentation, guides, reference materials, and instructional text
Purpose: establishes the scope of technical communication work and emphasizes the reader-focused nature of documentation
Example: API reference topics, tutorials, quickstart guides, and conceptual explanations all constitute content
content types
| Aspect | Content | Structured Content | Modular Content | Kinetic Content | Liquid Content |
|---|---|---|---|---|---|
| Definition | anything written for someone else to read | content organized into discrete, labeled components | self-contained units that function independently | content designed for dynamic combination with minimal human intervention | content that adapts in real-time based on user context |
| Key Technology | any writing/publishing tool | content management systems, databases | component-based CMS, DITA | automation platforms, APIs, real-time data integration | AI, LLMs, agentic systems |
| Primary Goal | communicate information | enable systematic reuse | maximize consistency across contexts | automate personalization and distribution | transform format and delivery based on user needs |
| Human Involvement | high - manual creation and updates | moderate - structured authoring | moderate - component maintenance | low - automated assembly | minimal - AI-driven transformation |
| API Docs Example | traditional endpoint documentation page | endpoint data in separate, queryable fields | reusable error code descriptions | docs with real-time API status and user-specific examples | text documentation that converts to audio or adjusts detail level automatically |
Related Terms: CMS, content governance, content strategy, DAM, Diátaxis, documentation audit, information architecture, kinetic content, liquid content, metadata, modular content, rhetorical approach, structured content, technical communication, tone, voice
Source: Docs By Design: "Audience, Market, Product Webinar"
CTA
Definition: acronym for call to action; content element that prompts a reader to take a specific next step — sign up, download, try a feature, contact sales — typically expressed as a button, banner, link, or inline prompt
Purpose: directs reader behavior toward a desired outcome; in API docs contexts, CTAs often serve competing goals — product and marketing teams use them to drive trial signups or downloads, while docs goals center on helping readers complete the task that brought them to the page; understanding this tension informs placement and framing decisions that serve both goals without undermining either
Why this belongs in Writing Style: describes a rhetorical device
and content design decision rather than a tool or platform; CTA
effectiveness depends on language, placement, and reader context —
writing concerns rather than infrastructure concerns; most actionable
as a question of how and where to prompt action without interrupting the
reader's task
CTA Considerations:
| Placement | Effect | Risk |
|---|---|---|
| Page Chrome — header, footer, nav | Reaches readers without interrupting content | Lower visual prominence |
| End of Page | Catches readers who completed the task | Readers who left early don't see it |
| Mid-content Banner | High visual prominence | Banner blindness — Readers filter it as an ad; slight annoyance guaranteed |
| Contextual Inline Link | Directly relevant to reader's current task | Requires tailoring per page — "Want to try this specific feature?" rather than generic copy |
Example: a team adds a large mid-page download CTA to high-traffic user manual pages to drive free trial signups; readers who are already using the manual likely have the product, and readers who don't have trained themselves to scroll past anything resembling an ad banner; a contextual inline CTA tailored to the page — "Want to try this feature? Sign up for a free trial" — reduces the generic ad signal and targets readers who haven't converted; placing a download link in the page chrome reaches the same audience without interrupting the task that brought them to the page
Related Terms: API overview topic, banner blindness, docs theater, DX, progressive disclosure, rhetorical approach, Seven-Action Documentation Model, tone, UX
Sources:
- Wikipedia: "Call to action (marketing)"
- Write the Docs #general channel discussion, March 2026
curse of knowledge
Definition: also known as curse of expertise and/or expert's curse; cognitive bias where a subject matter expert unconsciously assumes that others share the same background knowledge, making it difficult to communicate clearly with less-informed audiences
Purpose: explains one of the most common sources of unclear API docs — writers who built or deeply understand a system struggle to anticipate what a reader encountering it for the first time needs to have explained; recognizing the bias is the first step toward writing docs that serve the actual audience rather than the imagined one; also surfaces in user research contexts, where internal users make poor test candidates because their existing knowledge contaminates results
Why this belongs in Writing Style: describes a cognitive pattern
that directly shapes language and docs decisions at the
drafting and revision stage; it is most actionable as a writing
concern — define acronyms on first use, explain context that feels
obvious, write for the reader with no background — rather than as
a strategic or architectural framework; Frameworks & Strategy
covers high-level conceptual models, while the curse of knowledge
is a bias writers actively write against sentence by sentence
Example: a developer who built an authentication service documents the token refresh flow without explaining what a refresh token is or why expiry matters — both feel obvious after months of working on the system; a tech writer reviewing the doc flags the gap because they encountered the same docs as a first-time reader and noticed what was missing; the fix isn't more docs, it's writing that treats assumed context as a liability
Related Terms: cognitive dimensions of API usability, content strategy, domain knowledge, DX, knowledge management, progressive disclosure, usability testing, UX
Sources:
- passo.uno: "Do it yourself: User research for technical documentation" by Fabrizio Ferri-Benedetti
- Wikipedia: "Curse of knowledge"
docs theater
Definition: the act of creating documentation for the sake of it, so that a box can be checked, an issue closed, or a project completed; docs that perform thoroughness or credibility rather than serving genuine reader needs
Purpose: names a pattern that causes readers to distrust docs instinctively — when polish substitutes for substance, readers lose reliable signals for evaluating docs quality; recognizing docs theatre helps writers avoid it and helps readers calibrate trust appropriately
Why this belongs in Writing Style: describes a rhetorical
and communicative failure mode rather than a workflow practice or
tool-specific issue; fundamentally a question of voice, intent,
and the relationship between form and content
docs theater vs related terms
| Term | Description | Distinction |
|---|---|---|
| docs-as-tests | validates that docs accurately reflect product behavior | the practice designed to detect and prevent docs theatre — content that passes surface inspection but fails functional validation |
| astrothorough | excessive, AI-assisted, or artificially inflated comprehensiveness — fake thoroughness in the style of astroturf | the fake signal is coverage and volume; distinct from gloss or claptrap, which fake surface finish rather than completeness |
| docsturing | docs that perform confidence or authority through posture rather than substance | implies active concealment — something is rotting underneath the polish, not merely absent |
| SUS | slop under surface — content that appears credible but conceals inaccuracy, decay, or gaps beneath a polished exterior | describes the condition of the content; docsturing is the behavior, SUS is what you find when you look underneath |
| technobabble | language that performs technical expertise without conveying meaning or serving reader needs | the content-level failure that produces docs theatre; see Annie Mueller: "How I, a non-developer, read the tutorial you, a developer, wrote for me" |
| wikibait | looks authoritative and reference-like but is too curated to be reliable; includes thorough-tease — content that earns trust on first read then loses it on closer inspection | the fake signal is authority and comprehensiveness; the failure may only reveal itself over time |
Community Insights: the observation — that overly thorough internal docs trigger more suspicion than docs with visible gaps — points to a deeper principle: readers use imperfection as a signal of authenticity; docs theatre exploits the surface markers of quality while removing the underlying substance that justified trusting them
Example: an internal engineering RFC with a perfectly structured table of contents, smooth prose, and zero open questions — despite covering a system still under active design; a reader familiar with the system notices the gaps the docs don't acknowledge, and trusts it less than a rougher draft would have
Related Terms: AI-assisted documentation, banner blindness, Clayton's Docs, CTA, docs-as-code, docs-as-ecosystem, docs-as-tests, RFC, Seven-Action Documentation Model
Sources:
- passo.uno: "When docs become performance art, everybody loses" by Fabrizio Ferri Benedetti
- passo.uno: "Code wikis are documentation theater as a service" by Fabrizio Ferri Benedetti
- Write the Docs #ai channel discussion, March 2026
kinetic content
Definition: content creation philosophy and structural approach; the process of automating the recombination of modular content and the content designed for combination and recombination dynamically, integrating real-time data, and distributing to multiple audiences with minimal human intervention
Purpose: enables automation and personalization of documentation delivery while maintaining accuracy and relevance; represents a technology-agnostic approach to flexible content that emphasizes properties like personalization, data integration, automation, omnichannel delivery, interoperability, and scale
Why this belongs in Writing Style: describes a content creation
philosophy and structural approach that focuses on content design
and organization rather than the specific AI technologies that might
implement it; represents a strategic writing methodology similar to
modular documentation or structured authoring, emphasizing the principles
of dynamic content assembly rather than the tools that enable it
Example: API documentation that automatically updates code examples based on the user's preferred programming language, authentication method, or API version; or endpoint documentation that pulls real-time status information and adjusts examples based on current API capabilities
Related Terms: CMS, content, liquid content, modular content, real-time, structured content
Source: Kinetic Council, "What is Kinetic Information?"
modular content
Definition: the process of making structured content reusable; content strategy of self-contained content units designed to function independently and enable tech writers to combine units in different ways across documentation
Purpose: maximizes content reuse and maintains consistency when the same information appears in multiple contexts; builds on structured content principles to enable dynamic content assembly; supports discoverability and exposes relationships that glue individual topics together
Example: a reusable authentication code snippet that appears in multiple API endpoint examples, or a standard error response description used across reference documentation without manual copying
Related Terms: CMS, content, kinetic content, liquid content, progressive disclosure, structured content
Sources:
- Crafter Software Corporation, Content Management: "What is Modular Content?" by Amanda Lee
- MadCap Software, MadBlog: "What is Modular Writing?" by Una Cogavin
progressive disclosure
Definition: content design principle of presenting only the minimum information needed at each stage of a user's interaction, revealing additional detail progressively as the user needs it; structuring information in tiers, so the right content loads at the right time
Purpose: reduces cognitive load and improves comprehension by avoiding information overload; in agent configuration contexts, reduces token consumption by loading only relevant context rather than exhaustive docs upfront
Example: instead of including full style guide content in an
AGENTS.md file, include a compressed reference link — the agent
loads the full guide only when needed; Vercel applied this to reduce
their initial agent docs references from 40KB to 8KB,
an 80% reduction
Related Terms: agent configuration, banner blindness, CTA, curse of knowledge, domain knowledge, information architecture, knowledge management, modular content, structured content
Sources:
- Instruction Manuel: "The Most Actionable Docs Around: Agent Configs" by Manny Silva
- Nielsen Norman Group: "Progressive Disclosure" by Jakob Nielsen
rhetorical approach
Definition: framework that treats communication as action embedded in culture, values, and power structures, recognizing that each communication situation is unique and requires analysis of its specific context
Purpose: ensures technical writers consider audience, purpose, and context when crafting API documentation rather than applying one-size-fits-all solutions
Example: choosing between formal reference documentation for experienced developers versus conversational tutorials for beginners demonstrates rhetorical awareness
Related Terms: active voice, banner blindness, content, CTA, tone
Sources:
- Docs By Design: "Audience, Market, Product Webinar"
- Pressbooks, University of Minnesota, Introduction to Technical and Professional Communication: "Understanding Rhetoric" by Brigitte Mussack and Evelyn Dsouza
structured content
Definition: foundational approach to organizing content; content strategy that treats digital content like data; demonstrates content organized into discrete, clearly labeled components documentation teams can easily manage, query, and use systematically across multiple outputs
Purpose: enables content reuse, consistency, and efficient maintenance by separating content from presentation; forms the foundation for modular, kinetic, and liquid content approaches
Example: an API endpoint description stored as separate fields - method, path, parameters, response codes - in a CMS rather than as a single block of text, allowing the same information to appear in reference docs, tutorials, and SDK documentation
Related Terms: CMS, content, kinetic content, liquid content, metadata, modular content, progressive disclosure, reference, SDK
Sources:
- ButterCMS: "Structured Content 101: What Is It? Why Do You Need It?" by Alex Williams
- Wikipedia: "Structured content"
tone
Definition: the attitude or emotional quality conveyed through word choice, sentence structure, and stylistic decisions in written communication and/or content
Purpose: establishes the relationship between documentation and readers, affecting engagement, trust, and comprehension
Example: conversational tone uses contractions and direct address - "you'll need to authenticate," while formal tone avoids both - "authentication is required"
Related Terms: active voice, content, CTA, rhetorical approach, voice
Source: API Docs Glossary: Style Guide
voice
Definition: the consistent personality and perspective expressed throughout documentation, distinct from tone which can vary by context
Purpose: creates cohesive documentation that readers recognize as coming from a unified source regardless of who writes individual pieces
Example: a documentation voice might be "helpful but not condescending" or "technically precise but accessible," maintained across all content types
Related Terms: active voice, content, rhetorical approach, tone
Source: API Docs Glossary: Style Guide