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

Reconciling quality criteria with validation dimensions

The six criteria above describe what good documentation achieves for readers. But how do you verify that your documentation meets them? This repository’s validation system (see 05-validation-and-quality-assurance.md) operationalizes these principles through seven validation dimensions. The mapping isn’t one-to-one—some criteria span multiple dimensions, and some dimensions serve several criteria.

The table below reconciles the six quality criteria with the seven validation dimensions. Each row shows which validation dimensions contribute evidence for a given quality criterion:

Quality criterion Primary validation dimensions How the dimensions verify it
Findability Structure Heading hierarchy, TOC presence, logical navigation, cross-references
Understandability Readability, Grammar Flesch scores, sentence length, active voice, correct syntax, jargon density
Actionability Logical Coherence, Coverage Complete procedures without gaps, prerequisites identified, logical step flow
Accuracy Fact Accuracy, References Technical claims verified, code examples tested, sources authoritative and current
Consistency Grammar, Structure Uniform terminology, standardized formatting, predictable patterns, coherent voice
Completeness Coverage, References All subtopics addressed, edge cases covered, claims supported by citations

What the table reveals:

  • No dimension is wasted. Every validation dimension contributes to at least one quality criterion, meaning the validation system has no dead weight.
  • Some dimensions pull double duty. Grammar supports both Understandability and Consistency. Structure supports both Findability and Consistency. References supports both Accuracy and Completeness. This overlap is intentional—it reflects how quality attributes interact in practice.
  • Actionability is the hardest to validate. It depends on Logical Coherence (are steps in the right order?) and Coverage (are all steps present?)—two dimensions that require human judgment rather than automated scoring.
  • Readability serves one criterion directly. Its narrow focus (language accessibility) makes it the most automatable dimension, but it doesn’t capture deeper comprehension. See 09-measuring-readability-and-comprehension.md for measurement approaches that go beyond readability scores.

This reconciliation helps you understand why each validation dimension exists. When you run the readability review prompt, you’re verifying Understandability. When you run the structure validation, you’re verifying Findability and Consistency. The validation system isn’t an arbitrary checklist—it’s a systematic operationalization of the quality criteria that define good documentation.

On deliberate overlap with Article 05: This article defines the six quality criteria and maps them to validation dimensions (definition level). Article 05: Validation and Quality Assurance introduces the Quality Triangle and operationalizes the criteria into automated and manual checks (application level). Both perspectives are intentional—the three-level hierarchy (Triangle → criteria → dimensions) requires both articles. See Article 08 for the series redundancy policy.

🏗️ 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:

⚖️ Diátaxis quality theory: functional vs. deep quality

The Diátaxis framework doesn’t just organize documentation into four types—it also proposes a theory of quality that distinguishes two fundamentally different kinds of documentation excellence. This distinction matters because most validation systems (including this repository’s) focus on one kind while the other requires a different approach entirely.

Functional quality

Functional quality encompasses the objectively measurable properties of documentation:

  • Accuracy — Does the documentation correctly describe what it claims to?
  • Completeness — Are all necessary topics covered?
  • Consistency — Are terminology, style, and structure uniform?
  • Usefulness — Does the documentation serve a practical purpose?
  • Precision — Is information specific enough to act on?

These characteristics are independent of each other. Documentation can be accurate without being complete. It can be complete but inaccurate and inconsistent. It can be accurate, complete, consistent, and also useless.

Attaining functional quality requires discipline, attention to detail, and high technical skill. Any failure to meet these standards is readily apparent to users.

Deep quality

Deep quality encompasses characteristics that can’t be reduced to checklists or metrics:

  • Feeling good to use — The documentation is pleasant to read and navigate
  • Having flow — Content moves naturally from one idea to the next
  • Fitting to human needs — Documentation anticipates what users need at each moment
  • Being beautiful — Structure, language, and presentation create an aesthetic experience
  • Anticipating the user — Content appears where and when users need it

Unlike functional quality characteristics (which are independent), deep quality characteristics are interdependent. Having flow and anticipating the user are aspects of each other. It’s hard to see how documentation could feel good to use without fitting to human needs.

How they relate

Functional quality and deep quality relate in specific, asymmetric ways:

Dimension Functional quality Deep quality
Independence Characteristics are independent of each other Characteristics are interdependent
Objectivity Objective—measured against the world Subjective—assessed against the human
Measurement Can be measured with numbers (Flesch scores, completeness %) Can only be enquired into, judged
Relationship Can exist without deep quality Conditional upon functional quality
Experience Represents constraint (tests we might fail) Represents liberation (work of creativity)

The asymmetry matters: documentation can meet every functional quality standard and still fail to exhibit deep quality. There’s plenty of documentation that’s accurate, consistent, and even useful—but also awkward and unpleasant to use. However, documentation will never have deep quality without first being accurate, complete, and consistent. The moment readers encounter a factual error or an inconsistency, the experience is tarnished.

Diátaxis and quality

Diátaxis itself can’t address functional quality directly—that’s the work of disciplined craft. But it serves functional quality indirectly by exposing lapses. Applying Diátaxis structure to existing documentation often makes problems suddenly apparent: moving explanatory content out of a tutorial highlights sections where readers were left to work things out for themselves; structuring reference docs to mirror code architecture makes gaps in coverage clearly visible.

For deep quality, Diátaxis can do more. It helps documentation fit user needs by describing documentation modes based on those needs. It preserves flow by preventing disruptions—like when an explanation digression interrupts a how-to guide. But Diátaxis offers principles, not a formula. It can’t substitute for skills in user experience design, visual design, or the craft of writing itself. As the framework’s creator notes: “Using Diátaxis does not guarantee deep quality… but what Diátaxis can do is lay down some conditions for the possibility of deep quality.”

Connection to this repository’s validation: The seven validation dimensions in Article 05 and the reconciliation table in the quality criteria section above primarily measure functional quality. Deep quality—flow, beauty, anticipation—requires human judgment and can’t be captured by automated scoring. This is why the Diátaxis framework complements rather than replaces the validation system.

On deliberate overlap with Article 09: This article provides the full definition and theory of functional vs. deep quality—definitions, characteristics, comparison table, and relationship to Diátaxis. Article 09: Measuring Readability and Comprehension applies the distinction to measurement strategy—what readability formulas can and can’t capture, and what a complete measurement approach requires. See Article 08 for the series redundancy policy.

📋 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

Deep dive available: For a detailed comparative analysis of these guides — including voice and tone differences, mechanical rules, content philosophy, accessibility approaches, and decision matrices for choosing between them — see 03-microsoft-compared-to-other-guides.md.

Guide summaries and when to prefer each

Microsoft Writing Style Guide — “Write like you speak.” Conversational, inclusive, accessible. Strong on bias-free communication, global English, and practical product examples. When to prefer: Developer-facing content for enterprise software, balancing technical precision with approachability.

Google Developer Documentation Style Guide — “Documentation is user assistance.” Exceptionally detailed word list, mobile-first scannability, strong internationalization focus. When to prefer: API documentation, international developer audiences, open-source projects.

Apple Style Guide — “Simplicity is sophistication.” Elegant prose over bullet points, human interface guidelines influence, premium brand voice. When to prefer: Consumer-facing documentation, user guides where brand voice and design integration matter.

Wikipedia Manual of Style — “Neutral point of view.” Encyclopedic third-person tone, rigorous citation requirements (every claim needs a reliable source), NPOV policy, consensus-driven decisions. When to prefer: Technical articles requiring source verification, multi-viewpoint analysis, knowledge base articles. Limitation for software docs: Second-person prohibition is awkward for how-to guides, and 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: framework understanding (Diátaxis), style guide awareness (Microsoft, Google, Apple, Wikipedia), and decision-making capability for when guidelines conflict.

Key takeaways

  • Documentation serves different needs — Tutorials, how-to guides, reference, and explanation each require distinct approaches based on Diátaxis principles
  • No single style guide is “best” — Choose based on audience, content type, and context
  • Wikipedia’s rigor raises quality standards — Source credibility, neutrality, and verifiability practices are valuable for all documentation
  • Consistency within a project matters most — Internal consistency outweighs strict adherence to any external standard
  • Decision frameworks resolve conflicts — Apply audience-first, content-type, and context-specific reasoning rather than arbitrary choices

Next steps

📚 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, Fact Accuracy, Logical Coherence, Coverage, References) with scoring thresholds.

Dual YAML Metadata [Internal Reference]
Guidelines for separating Quarto rendering metadata from validation tracking metadata.