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: 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
content
Definition: 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
Related Terms: rhetorical approach, tone, voice
Source: Docs By Design: "Audience, Market, Product Webinar"
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, content, 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
tone
Definition: the attitude or emotional quality conveyed through word choice, sentence structure, and stylistic decisions in written communication
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, rhetorical approach, tone
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, rhetorical approach, tone
Source: API Docs Glossary: Style Guide