Foundations of Technical Documentation

technical-writing
documentation
style-guides
best-practices
Comprehensive guide to technical documentation foundations, exploring authoritative frameworks including Diátaxis, Wikipedia, and major style guides from Microsoft, Google, and Apple
Author

Dario Airoldi

Published

January 14, 2026

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:

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):

  1. Use bigger ideas, fewer words
  2. Write like you speak
  3. Project friendliness
  4. Get to the point fast
  5. Be brief
  6. When in doubt, don’t capitalize
  7. Skip periods in UI labels
  8. Don’t use common words in new ways
  9. Use technical terms carefully
  10. 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:

  1. Neutral Point of View (NPOV) - Represent all significant viewpoints fairly, proportionately, without editorial bias
  2. Verifiability - Cite reliable sources for all non-obvious claims
  3. No Original Research - Report what sources say, don’t synthesize new conclusions
  4. 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 Google 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:

  1. Reduces ambiguity - Clear beats clever
  2. Increases accessibility - More people can use it
  3. Maintains consistency - Matches existing patterns
  4. 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):

How-to Guides (Work + Practical):

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:

  1. Framework Understanding - Diátaxis provides systematic guidance on what content to create and how to structure it based on user needs

  2. Style Guide Awareness - Microsoft, Google, Apple, and Wikipedia offer proven approaches to voice, tone, structure, and credibility that can be adapted to your context

  3. 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:

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.