Foundations of Technical Documentation
Foundations of Technical Documentation
Understanding the principles, frameworks, and decision-making strategies that underpin effective technical documentation across industries and platforms
Table of Contents
Introduction
Technical documentation exists at the intersection of technology, communication, and user experience. Whether you’re documenting APIs for developers, writing user guides for enterprise software, or creating knowledge bases for community projects, the fundamental question remains: what makes documentation effective?
This article establishes the foundational principles of technical documentation by:
- Analyzing authoritative frameworks (Diátaxis) that define documentation types
- Comparing major style guides (Microsoft, Google, Apple, Wikipedia)
- Identifying decision-making strategies when guidelines conflict
- Bridging theory with the practical implementation used in this repository
Prerequisites: Familiarity with documentation concepts is helpful but not required. This article serves as the foundation for the entire technical writing series.
What Makes Documentation “Good”?
Before examining specific frameworks and guidelines, we must establish criteria for quality documentation. Drawing from multiple authoritative sources, effective technical documentation exhibits these characteristics:
User-Centered Attributes
Findability - Users can locate the information they need quickly
- Clear information architecture
- Effective search optimization
- Logical navigation hierarchies
Understandability - Content matches the user’s knowledge level
- Appropriate technical depth
- Clear explanations of complex concepts
- Context provided when needed
Actionability - Users can accomplish their goals
- Concrete, specific guidance
- Complete procedures without gaps
- Working code examples
Content Quality Attributes
Accuracy - Information is factually correct and current
- Verified against reliable sources
- Regularly updated
- Version-specific when relevant
Consistency - Uniform style, terminology, and structure
- Predictable patterns across documents
- Standardized formatting
- Coherent voice and tone
Completeness - All necessary information is present
- Prerequisites identified
- Edge cases addressed
- Related concepts linked
Note: This repository’s validation system (see 05-validation-and-quality-assurance.md) operationalizes these principles through seven validation dimensions: grammar, readability, structure, facts, logic, understandability, and gaps.
The Diátaxis Framework: Four Documentation Types
The Diátaxis framework (from Ancient Greek διάταξις: “arrangement”) provides a systematic approach to understanding documentation needs.
Created by Daniele Procida, it identifies four distinct documentation types based on two axes:
Theoretical/Practical Axis:
- Practical documentation focuses on doing (hands-on activities)
- Theoretical documentation focuses on understanding (cognitive activities)
Study/Work Axis:
- Study mode: learning-oriented, acquisition phase
- Work mode: task-oriented, application phase
This creates four quadrants:
| Mode | Practical | Theoretical |
|---|---|---|
| Study | Tutorials Learning-oriented Lesson format |
Explanation Understanding-oriented Discussion format |
| Work | How-to Guides Task-oriented Step-by-step format |
Reference Information-oriented Description format |
Tutorials (Learning by Doing)
Purpose: Guide newcomers through their first successful experience
Characteristics:
- Learning-oriented, not goal-oriented
- Carefully controlled environment
- Immediate, visible results
- Build confidence through success
- Example: “Your First API Call: A Beginner’s Tutorial”
Key principle from Diátaxis: “A tutorial is an experience under the control of the teacher.”
How-to Guides (Solving Specific Problems)
Purpose: Direct users to accomplish specific real-world tasks
Characteristics:
- Goal-oriented and practical
- Assume some knowledge
- Focus on results, not learning
- Multiple valid approaches acceptable
- Example: “How to Authenticate with OAuth 2.0”
Key principle: How-to guides serve work, not study. They get users from A to B efficiently.
Reference (Information Lookup)
Purpose: Provide accurate, complete technical descriptions
Characteristics:
- Information-oriented
- Austere, formal tone
- Structure mirrors the codebase
- Comprehensive coverage
- Example: API endpoint documentation, configuration parameters
Key principle: Reference material describes the machinery. It must be accurate, consistent, and complete.
Explanation (Understanding Concepts)
Purpose: Clarify and illuminate the topic
Characteristics:
- Understanding-oriented
- Discusses alternatives and context
- Explores “why” questions
- Makes connections between concepts
- Example: “Understanding REST Architectural Constraints”
Key principle: Explanation deepens and broadens understanding. It discusses the bigger picture.
Why This Matters
The Diátaxis framework prevents common documentation failures:
Problem: “Our tutorial keeps failing for users”
- Diagnosis: Tutorial includes troubleshooting steps (how-to guide content)
- Solution: Keep tutorial environment simple; move troubleshooting to how-to guides
Problem: “Reference docs are too hard to read”
- Diagnosis: Reference includes conceptual explanations (explanation content)
- Solution: Keep reference austere; move concepts to explanation articles
Repository application: This technical writing series follows Diátaxis structure:
- Tutorial: Getting Started with IQPilot
- How-to: How to Structure Content for Copilot Instruction Files
- Reference: Validation Criteria
- Explanation: This article
Major Style Guides Comparison
Different organizations approach technical writing with varying priorities. Understanding these differences helps you make informed decisions when guidelines conflict.
Comparison Table: Core Principles
| Aspect | Microsoft Writing Style Guide 📘 | Google Developer Docs 📘 | Apple Style Guide 📘 | Wikipedia Manual of Style 📘 |
|---|---|---|---|---|
| Primary Audience | Developers, IT Pros, End Users | Developers, Technical Practitioners | General Consumers, Developers | General Public, Academic Community |
| Voice/Person | Second person (you) Conversational warmth |
Second person (you) Friendly but professional |
Second person sparingly Professional, polished |
Third person Encyclopedic, neutral |
| Active/Passive Voice | Prefer active voice Allow passive when appropriate |
Prefer active voice Use passive for objectivity |
Prefer active voice Human-centered language |
Both acceptable Context-dependent |
| Sentence Length | Prefer shorter sentences Readability focus |
Short, scannable sentences Mobile-friendly |
Varied for natural rhythm Clarity paramount |
Varies by context Completeness valued |
| Technical Depth | Layered (progressive disclosure) | Direct, no assumed knowledge | Invisible complexity | Comprehensive, linked |
| Accessibility Priority | High - WCAG guidelines | Very High - Global developer audience | High - Universal design | High - Screen reader compatible |
| Citation Requirements | Optional for common knowledge | Not emphasized | Minimal | Mandatory for all claims |
| Revision Culture | Regular updates Living document |
Continuous iteration | Controlled releases | Community-driven consensus |
Microsoft Writing Style Guide
Philosophy: “Write like you speak” - conversational, inclusive, accessible
Top 10 Principles (per learn.microsoft.com/style-guide):
- Use bigger ideas, fewer words
- Write like you speak
- Project friendliness
- Get to the point fast
- Be brief
- When in doubt, don’t capitalize
- Skip periods in UI labels
- Don’t use common words in new ways
- Use technical terms carefully
- Be inclusive and use bias-free language
Strengths:
- Strong emphasis on bias-free communication
- Detailed guidance on global English
- Comprehensive accessibility guidelines
- Practical examples from real Microsoft products
When to prefer Microsoft style: Developer-facing content for enterprise software, when balancing technical precision with approachability.
Google Developer Documentation Style Guide
Philosophy: “Documentation is user assistance” - clarity, scannability, global readability
Key Characteristics:
- Exceptionally detailed word list (preferred terms)
- Strong focus on internationalization
- Mobile-first mindset (short, scannable sections)
- API documentation standards (OpenAPI integration)
Strengths:
- Comprehensive guidance for API reference
- Explicit accessibility requirements
- Clear code example standards
- Global audience considerations
When to prefer Google style: API documentation, content for international developer audiences, open-source project documentation.
Apple Style Guide
Philosophy: “Simplicity is sophistication” - clean, human-centered, refined
Key Characteristics:
- Elegant prose over bullet points
- Human interface guidelines influence
- Minimal jargon and acronyms
- Premium brand voice
Strengths:
- Emphasis on user experience writing
- Integration with interface design
- Consistent premium brand voice
- Strong visual-text integration
When to prefer Apple style: Consumer-facing documentation, user guides for designed experiences, content where brand voice matters.
Wikipedia Manual of Style
Philosophy: “Neutral point of view” - encyclopedic, verifiable, community-maintained
Key Characteristics:
- Encyclopedic tone (third person, neutral)
- Rigorous citation requirements
- Neutral point of view (NPOV) policy
- Consensus-driven style decisions
Core Policies:
- Neutral Point of View (NPOV) - Represent all significant viewpoints fairly, proportionately, without editorial bias
- Verifiability - Cite reliable sources for all non-obvious claims
- No Original Research - Report what sources say, don’t synthesize new conclusions
- Manual of Style - Consistency in formatting, structure, and presentation
Unique Principles Not Emphasized Elsewhere:
Citation Rigor:
- Every claim requires a reliable source
- Source credibility classification
- “Citation needed” culture
- Verifiable over “true” (what can be verified in sources matters more than absolute truth)
NPOV Techniques:
- “According to X” attribution for contested claims
- Avoid “some people think” weasel words
- Weight viewpoints proportionally to their prominence in sources
- Present opinions as opinions, facts as facts
Strengths:
- Unparalleled source verification standards
- Clear guidance on handling controversial topics
- Systematic approach to neutrality
- Community-maintained quality control
When to prefer Wikipedia style: Technical articles requiring source verification, multi-viewpoint analysis, community documentation, knowledge base articles.
Limitations for software documentation:
- Second-person prohibition awkward for how-to guides (“A user opens the settings” vs “Open the settings”)
- Encyclopedic tone too formal for tutorials
- Over-citation can interrupt flow
Wikipedia’s Documentation Model
Wikipedia’s approach to documentation offers valuable lessons, particularly around source credibility, neutrality, and community maintenance.
Source Credibility Framework
Wikipedia categorizes sources with a sophistication worth emulating:
Primary Sources - Direct, firsthand evidence
- Original research papers
- Official specifications
- Source code
- Example: “The HTTP/1.1 specification (RFC 2616)”
Secondary Sources - Analysis and interpretation
- Academic articles
- Technical books
- Peer-reviewed journals
- Example: “Analysis of REST principles in Fielding’s dissertation”
Tertiary Sources - Compilations and summaries
- Encyclopedias
- Handbooks
- Almanacs
- Example: “MDN Web Docs summary of HTTP methods”
Reliable vs. Unreliable Indicators:
✅ Reliability indicators:
- Peer review process
- Editorial oversight
- Fact-checking standards
- Author expertise
- Institutional backing
❌ Unreliability indicators:
- Self-published without editorial review
- Anonymous authorship without accountability
- Advocacy sites with clear bias
- User-generated content without expert verification
- Broken or missing citations
Repository application: This aligns with our reference classification system:
- 📘 Official - Primary sources (Microsoft Learn, official docs)
- 📗 Verified Community - Reputable secondary sources (GitHub blog, academic)
- 📒 Community - Tertiary or less rigorous sources (Medium, personal blogs)
- 📕 Unverified - Broken links, unknown sources (flag for fixing)
See 06-citations-and-reference-management.md for complete citation guidelines.
Neutral Point of View (NPOV) Application
While pure NPOV isn’t suitable for all technical documentation, its principles inform quality writing:
Avoid stating opinions as facts:
- ❌ “React is the best JavaScript framework”
- ✅ “React is widely used in enterprise applications, with significant adoption by companies like Facebook, Netflix, and Airbnb”
Distinguish contested from uncontested claims:
- ❌ “This is the fastest algorithm”
- ✅ “Benchmarks from Smith et al. (2024) show O(n log n) performance”
Weight viewpoints appropriately:
- ❌ “Some developers prefer NoSQL databases” (weasel words)
- ✅ “According to the 2024 Stack Overflow survey, 38% of developers use NoSQL databases for production applications”
Repository application: Our validation system includes a “fact-checking” dimension specifically to verify claims against reliable sources.
Wikipedia’s Structural Patterns
Information Architecture:
- Lead section summarizes article without requiring further reading
- Table of contents provides navigation
- “See also” sections for related topics
- References section for source verification
- External links for additional resources
This repository adopts similar patterns:
- Article introductions establish scope and prerequisites
- TOCs in every substantial article
- Cross-references using markdown links
- References section with emoji-classified sources
- Related articles linked in context
Decision Frameworks: When Guidelines Conflict
Style guides sometimes contradict each other. Use these frameworks to decide:
Framework 1: Audience-First Decisions
Ask: Who is the primary reader?
| If primary audience is… | Prefer guidelines from… | Because… |
|---|---|---|
| End users (non-technical) | Apple, Microsoft | User-centered, conversational approach |
| Developers (practitioners) | Google, Microsoft | Technical precision, code-focused |
| Researchers/academics | Wikipedia | Verifiability, neutral tone |
| Mixed technical levels | Microsoft | Progressive disclosure, layered content |
| International/non-native English | Global readability standards |
Example decision:
- Conflict: Microsoft says “you can,” Apple says “users can,” Wikipedia says “one can”
- Resolution: Developer documentation → Use “you” (Google/Microsoft)
- Rationale: Developers expect direct instruction; formality creates distance
Framework 2: Content Type Decisions
Apply Diátaxis principles:
| If content type is… | Voice preference | Detail level | Source expectation |
|---|---|---|---|
| Tutorial | Second person (“you”) | Progressive, controlled | Minimal citations (focus on experience) |
| How-to | Second person imperative | Task-focused, efficient | Citations for non-obvious claims |
| Reference | Third person or neutral | Complete, exhaustive | Citations for all claims |
| Explanation | Third person or educational first-person plural (“we”) | Conceptual depth | Heavy citations for theories |
Example decision:
- Conflict: Should API reference use “you” or third person?
- Resolution: Reference type → Use third person (Wikipedia/formal style)
- Rationale: Reference describes the system, not user actions
Framework 3: Context-Specific Decisions
Consider these factors:
Brand/Organization Requirements:
- Corporate style guides override general principles
- Open-source projects may prefer community-established patterns
- Consistency with existing docs matters more than theoretical “best” choice
Platform/Medium:
- Mobile displays → Shorter sentences (Google style)
- Print documentation → More formal tone (Apple style)
- Interactive docs → Conversational style (Microsoft)
- API references → Structured, austere (Diátaxis reference principles)
Maintenance Considerations:
- Community-maintained → Clear, simple rules (like Wikipedia’s guidelines)
- Single-author → More flexibility for voice and style
- Automated generation → Strict structure requirements
Framework 4: The “Least Harm” Principle
When truly stuck, choose the option that:
- Reduces ambiguity - Clear beats clever
- Increases accessibility - More people can use it
- Maintains consistency - Matches existing patterns
- Simplifies maintenance - Easier for future editors
Example decision:
- Conflict: Capitalize “internet” or not?
- Historical context: AP Stylebook capitalized until 2016, then lowercased
- Current consensus: Microsoft, Google, Apple, Wikipedia all lowercase
- Resolution: Use “internet” (lowercase)
- Rationale: Current consensus, simpler rule (consistency > tradition)
Applying Foundations to This Repository
This repository’s documentation system emerged from these foundational principles:
Diátaxis Structure Mapping
Our content organization follows Diátaxis categories:
Tutorials (Study + Practical):
- GETTING-STARTED.md - IQPilot setup tutorial
- 01.01-introduction-to-quarto.md - Quarto learning path
How-to Guides (Work + Practical):
- 04.00-howto/ directory
- Prompt files in .github/prompts/
Reference (Work + Theoretical):
Explanation (Study + Theoretical):
- This article series (technical writing foundations)
- Concept articles in 03.00-tech/
Style Guide Synthesis
This repository synthesizes guidelines from multiple sources:
**Voice and Tone: Microsoft-inspired
- Second person for procedural content
- Conversational but professional
- Active voice preference (15-25 word sentences)
**Citation Requirements: Wikipedia-inspired
- Four-tier classification (📘📗📒📕)
- Every external claim referenced
- Source credibility assessment
**Accessibility: Google-inspired
- Readability targets (Flesch 50-70, Grade 9-10)
- Plain language principles
- Alternative text for images
**Structure: Diátaxis-informed
- Clear content type distinctions
- Cross-references between related types
- Navigation optimized for different user needs
Dual Metadata Architecture
Our unique contribution: separate Quarto rendering metadata from validation tracking.
Top YAML (Quarto):
---
title: "Article Title"
author: "Author Name"
date: "2026-01-14"
categories: [cat1, cat2]
description: "Brief description"
---Bottom YAML (Validation tracking):
<!-- Validation Metadata
validation_status: validated
last_validated: 2026-01-14
validation_scores:
grammar: 95
readability: 88
structure: 92
-->This separation follows the single-responsibility principle: Quarto metadata controls rendering; validation metadata tracks quality.
See 02-dual-yaml-metadata.md for complete guidelines.
Conclusion
Effective technical documentation rests on three pillars:
Framework Understanding - Diátaxis provides systematic guidance on what content to create and how to structure it based on user needs
Style Guide Awareness - Microsoft, Google, Apple, and Wikipedia offer proven approaches to voice, tone, structure, and credibility that can be adapted to your context
Decision-Making Capability - When guidelines conflict, apply audience-first, content-type, and context-specific frameworks rather than arbitrary choices
Key takeaways:
- Documentation is not one thing - tutorials, how-to guides, reference, and explanation serve different needs
- No single style guide is “best” - choose based on audience, content type, and context
- Wikipedia’s rigor around sources and neutrality raises quality standards
- Consistency within a project matters more than adhering to any external standard
- This repository synthesizes best practices while maintaining coherent, maintainable patterns
Next in this series:
- 01-writing-style-and-voice-principles.md - Deep dive into active/passive voice, readability formulas, and sentence structure
- 02-structure-and-information-architecture.md - Progressive disclosure, LATCH framework, TOC strategies
- 05-validation-and-quality-assurance.md - How this repository operationalizes these principles through validation
References
Official Style Guides
Microsoft Writing Style Guide 📘 [Official]
Comprehensive style guide for Microsoft products. Emphasis on conversational tone, bias-free communication, and accessibility.
📚 Deep Dive: For comprehensive analysis of Microsoft’s style principles, see the Microsoft Writing Style Guide Series, including in-depth coverage of voice, mechanics, and machine-readable rules for prompts and agents.
Google Developer Documentation Style Guide 📘 [Official]
Detailed guidance for developer-facing documentation. Strong focus on global readability, API standards, and accessibility.
Apple Style Guide 📘 [Official]
Refinement-focused style guide emphasizing simplicity, human-centered language, and brand voice consistency.
Frameworks and Standards
Diátaxis - A systematic approach to technical documentation 📗 [Verified Community]
Daniele Procida’s framework for understanding documentation through four types: tutorials, how-to guides, reference, and explanation.
Wikipedia Manual of Style 📘 [Official]
Comprehensive style guide for encyclopedic content. Core resource for neutral point of view, citations, and verifiability standards.
Wikipedia Neutral Point of View Policy 📘 [Official]
Fundamental policy for representing viewpoints fairly without editorial bias. Key guidance on due weight, balance, and source selection.
Community Resources
Write the Docs - Style Guides 📗 [Verified Community]
Curated collection of style guide resources, including links to major tech company guides and guidance for creating your own.
Red Hat Documentation Style Guide 📗 [Verified Community]
Open-source documentation standards. Strong example of community-maintained style guidelines.
Repository-Specific Documentation
Documentation Instructions [Internal Reference]
This repository’s comprehensive style guide with voice, tone, formatting, and citation requirements.
Validation Criteria [Internal Reference]
Seven validation dimensions (grammar, readability, structure, logic, facts, understandability, gaps) with scoring thresholds.
Dual YAML Metadata [Internal Reference]
Guidelines for separating Quarto rendering metadata from validation tracking metadata.