Developer Documentation Vocabulary

The four main documentation types each serve a distinct purpose — knowing which to use prevents wasted reading time.

The Diátaxis framework defines four documentation types:
• Reference — factual descriptions; consulted, not read linearly (API docs, parameter lists)
• How-to guides — goal-oriented, step-by-step; assumes reader knows the goal (recipes, installation guides)
• Tutorials — learning-oriented; reader builds something working from scratch, learns by doing
• Explanations / Concepts — understanding-oriented; explains why, not how (architecture overviews, design decisions)

Why the distinction matters:
• If you send a beginner to reference docs, they don't have enough context yet = frustration
• If you send an expert to a tutorial, they don't want the learning scaffolding = wasted time
• Finding the right doc type for the right use case is a DevRel skill

Key vocabulary:
• Reference documentation — precise, complete descriptions of a system's components and behavior
• How-to guide — a goal-oriented document that walks through accomplishing a specific task
• Tutorial — a learning-oriented document where the reader does something to acquire new skills
• Conceptual documentation — explanations of how and why a system works, not how to use it
• Diátaxis framework — a documentation structure framework by Daniele Procida organizing docs by purpose

A circular definition (also called a tautology) restates the term without explaining it — the reader is no better off than before reading.

Circular: "The timeout parameter specifies the timeout."
Non-circular: "The timeout parameter specifies how many milliseconds to wait for a server response before the request is cancelled and returns a TIMEOUT_ERROR. Defaults to 30000 (30 seconds)."

What the non-circular version adds:
• Unit — "milliseconds" (not seconds? not micro-seconds?)
• What happens at timeout — "request is cancelled and returns TIMEOUT_ERROR"
• Default value — "Defaults to 30000 (30 seconds)" (necessary to reason about the parameter)

Common API doc anti-patterns:
• Circular definition — "title is the title of the item"
• Missing unit — "delay: 500" (500 what?)
• Missing default — "optional parameter" (what happens if I omit it?)
• Missing error behavior — "what if I pass -1?"

Key vocabulary:
• Circular definition — a definition that uses the word it defines as part of the explanation
• Parameter description — the documentation for a single function or API parameter
• Default value — the value used when a parameter is not explicitly provided
• Boundary conditions — the behavior at the limits of a parameter's valid range
• API reference documentation — complete, precise descriptions of every parameter, method, and return value

Documentation debt is the documentation analog of technical debt — the cost of work deferred that accumulates over time.

Common forms of documentation debt:
• Outdated docs — code changed but docs still describe the old behavior
• Missing docs — shipped features with no documentation
• Misleading docs — docs that are technically accurate but lead developers to wrong conclusions
• Stale examples — code samples that no longer compile or run against the current version
• Broken links — references to documentation pages that no longer exist

Why documentation debt compounds:
• Every developer who hits a wrong doc creates a support ticket
• Every support ticket that isn't fixed in docs gets asked again
• The older the wrong doc, the harder it is to find and fix (no one owns it)

The analogy to technical debt is intentional — both represent deferred work with compounding interest in support costs and developer frustration.

Key vocabulary:
• Documentation debt — the accumulated cost of deferred documentation work
• Stale documentation — documentation that was once accurate but is no longer correct
• Docs rot — informal term for documentation that degrades over time without active maintenance
• Technical debt — accumulated shortcuts in code that require future work to fix
• Documentation audit — a systematic review of existing documentation for accuracy and completeness

Docs-as-code is a documentation methodology that applies software engineering practices to documentation creation and maintenance.

Core elements of docs-as-code:
• Markup language — Markdown or AsciiDoc (not Word or Confluence WYSIWYG)
• Version control — documentation stored in Git alongside the code it documents
• Pull request workflow — documentation changes reviewed like code changes
• CI/CD deployment — docs automatically built and deployed when merged (using tools like Docusaurus, MkDocs, Sphinx)
• Tests for docs — link checkers, code sample validation, spelling/style linters

Why docs-as-code solves common problems:
• Docs stay in sync with code — they live in the same repo, in the same PR
• Same review process — engineers don't need a separate tool to critique docs
• History and blame — git log shows who changed what and when
• Rollback — documentation mistakes can be reverted like code mistakes

Key vocabulary:
• Docs-as-code — treating documentation like software: versioned, reviewed, and deployed through engineering workflows
• Markdown — a lightweight markup language commonly used in docs-as-code workflows
• Static site generator (SSG) — a tool that converts Markdown docs into a hosted website (Docusaurus, MkDocs, Astro)
• Documentation CI/CD — automated pipelines that build, test, and deploy documentation
• Co-located documentation — documentation stored in the same repository as the code it describes

Progressive disclosure is an information design principle: show essential information first, provide depth on request or via progressive navigation.

Applied to API documentation:
• First level — simple, common example (copy-paste ready, annotated inline)
• Second level — expandable parameters section with all options and defaults
• Third level — deep conceptual explanation link for users who need to understand internals

Example in practice:
Stripe's API docs show the minimal code example first, then expandable sections for optional parameters, then a separate "how payments work" conceptual guide — three levels of disclosure, each optional.

Why it matters for DevRel:
• A beginner sees the working example and ships; the advanced override section doesn't confuse them
• An expert can expand to see all parameters without wading through beginner scaffolding
• Cognitive overload from too much upfront information is one of the top causes of developer abandonment

Key vocabulary:
• Progressive disclosure — presenting information in layers, from essential to complex
• Cognitive load — the mental effort required to understand a piece of documentation
• Developer experience (DX) — the holistic quality of a developer's journey through a tool, including its documentation
• Annotated code sample — a code example with inline explanations of what each line does
• Documentation information architecture — the structural organization of a documentation site