How to Organize Technical Documentation

The Documentation Problem Engineering Teams Actually Have

Most engineering teams don't have a documentation problem. They have a retrieval problem.

There's usually documentation somewhere — in the repository's README, in a Confluence wiki, in a Google Drive folder, in Notion, in Slack pinned messages, in PR descriptions from six months ago. The problem is that it's in all of these places with no consistent organization, and finding a specific piece of documentation requires either knowing exactly where to look or asking someone who does.

This is the retrieval problem: the information exists, but the cost of accessing it is high enough that engineers often re-derive knowledge from first principles, ask a colleague who is then interrupted, or do without and accumulate technical debt from decisions made without full context.

Good technical documentation organization doesn't mean having more documentation — it means organizing what exists so the right document is findable in under a minute by someone who doesn't know where to look.

---

The Diátaxis Framework: A Structure That Works

The Diátaxis framework, developed by Daniele Procida and presented in detail at diataxis.fr, identifies four types of technical documentation that serve different purposes and different user needs. Understanding the distinction prevents the most common documentation organization error: mixing types that should be separate.

Tutorials: Learning-oriented. A tutorial teaches a skill through a specific, guided task. The reader follows along and achieves a working result. The goal is learning, not reference. Example: "Getting started with the payments service: set up your local environment and process your first test charge."

How-to guides: Task-oriented. A how-to guide helps the reader accomplish a specific, real-world task. It assumes the reader has the basic knowledge (unlike a tutorial) and wants to accomplish a goal. Example: "How to configure rate limiting for the API."

Reference: Information-oriented. A reference document provides accurate, complete technical description: all the parameters, all the methods, all the configuration options. It's consulted, not read. Example: "API endpoint reference" or "Configuration option reference."

Explanation: Understanding-oriented. An explanation document discusses a concept, provides context, and helps the reader understand why — not how. Example: "How the authentication token lifecycle works and why it's designed this way."

Mixing these types in a single document or a single organizational category produces documents that do none of the four jobs well. The README that tries to be tutorial + how-to + reference + explanation is a document that serves none of these needs efficiently.

---

Documentation Locations: The Right Principle

Documentation belongs where engineers will look for it when they need it. This is more important than any specific folder structure or tool choice.

In the repository (docs/ directory):

• Architecture Decision Records (ADRs)
• Developer setup guides for this specific service
• API documentation (or links to generated docs)
• Runbooks for this service
• Changelog

Rationale: Documentation that describes this specific service belongs with the service. It's updated by the same PR that changes the service; it's found by engineers who are already looking at the repository.

In the team wiki (Confluence, Notion, GitHub wiki):

• Team processes and conventions (PR workflow, code review standards, deployment process)
• Cross-service documentation (how systems interact, shared infrastructure)
• Onboarding documentation
• Meeting notes and team decisions

Rationale: Cross-cutting documentation that spans multiple repositories or that is organizational rather than technical belongs in a shared team space, not in any one repository.

In code:

• Inline comments explaining non-obvious decisions (the WHY, not the WHAT)
• Package/module documentation (docstrings, godoc, JSDoc)
• Type definitions and schema comments

Rationale: Documentation that is most useful at the moment of reading the code belongs with the code. An engineer reading a function that does something non-obvious benefits from a comment there, not from a separate document they'd have to find.

The single-source-of-truth principle: Each piece of information has exactly one authoritative location. If the same information appears in three places, all three become outdated at different rates and no one knows which is authoritative. When information must appear in multiple places (a summary here, the full detail there), one document is the source of truth and the other links to it.

---

A Naming and Linking Convention That Works

Finding the right document quickly depends on naming and linking:

Document names that describe what the document does:

• "API endpoint reference" not "API docs"
• "Local development setup" not "Setup"
• "Deployment process" not "Deployment"
• "Event sourcing explanation" not "Architecture notes"

Names that describe the content type and scope are faster to scan in a list than names that require opening the document to understand its scope.

The entry-point document for every service: Every service or major component should have one entry-point document that orients a new engineer: what the service does, the primary documentation links (setup, API reference, runbooks, ADRs), and who to ask when the documentation doesn't answer the question. This document is the index; the other documents are the content.

Consistent cross-linking: A runbook that mentions a specific configuration option should link to the reference where that option is documented. A how-to guide that assumes the reader has completed setup should link to the setup guide. Cross-linking is not duplicating information — it's connecting it so an engineer following one path can reach related information without navigating from the top.

---

The Documentation Debt Audit

Most engineering teams discover their documentation problem when they're most inconvenienced by it: during onboarding of a new engineer, during an incident where the runbook is missing, or when a key team member leaves. The discovery is reactive rather than proactive.

A documentation audit takes two hours and produces an actionable list:

Step 1: List what documentation should exist for each service or system.

For each service you maintain, what documentation would an engineer without prior context need to:

• Set up a local development environment?
• Understand what the service does and its role in the system?
• Understand the API contracts?
• Operate the service (deployment, rollback, common incidents)?
• Make architectural decisions about the service?

Step 2: Identify what exists and where. For each item in the list: does it exist? Is it findable? Is it accurate?

Step 3: Triage the gaps. Not all documentation gaps are equal. Prioritize:

• Gaps that would block a new engineer during onboarding (highest priority)
• Gaps that are exposed during incidents (high priority)
• Gaps that affect daily development (medium priority)
• Gaps in reference documentation for rarely-used features (low priority, add as needed)

Step 4: Assign owners and deadlines. Documentation gaps are work items. They need owners and timelines just like feature work. "The team will improve documentation" without a specific assignment and deadline produces nothing.

---

Keeping Documentation Current

The most common way documentation becomes stale is that it's not updated when the system changes. This is a process problem, not a willpower problem.

The PR checklist item: Every PR template should include: "Does this change affect documentation? If yes, is the relevant documentation updated in this PR?" This is the most reliable intervention — it asks the question at the moment when the engineer is most likely to know the answer and most able to take action.

The "docs must pass" gate: For teams with mature CI/CD pipelines, a linting step that checks whether documentation links are broken, whether the setup guide refers to dependencies that no longer exist in the repository, or whether the API spec is out of sync with the code catches some staleness automatically.

Documentation review in postmortems: When an incident reveals a missing or outdated runbook, the postmortem action item includes updating the runbook. This is the reactive version; the PR checklist is the proactive version.

The "ownership" model: Each piece of documentation has a named owner who is responsible for its accuracy. This is not a dedicated documentation role — it's the engineer who owns the system or the subsystem. Ownerless documentation is everyone's responsibility and therefore no one's.

---

Documentation as Code: Keeping It With the System

The "docs as code" approach treats documentation in the same workflow as code: written in plain text (Markdown), stored in version control, reviewed via the same PR process, and deployed (often as a static site) from the same pipeline.

Benefits:

• Documentation is reviewed and approved before it's published, just like code
• Documentation changes appear in the same git history as code changes — finding "when was this documented" is the same as finding "when was this code changed"
• Automation (linting, link checking, spell checking) applies to documentation just as it does to code
• The PR process for documentation changes includes the same code review and sign-off as code

Tools for "docs as code":

• MkDocs with Material theme: generates a static documentation site from Markdown files; excellent default look; widely used in Python and general engineering teams
• Docusaurus: Facebook's React-based documentation framework; good for teams already in the React ecosystem; excellent for public-facing docs
• GitBook: connects to a GitHub repository; generates a polished docs site; commercial but has a free tier
• Mintlify: modern developer docs platform; integrates with GitHub; good tooling for API docs alongside prose documentation

---

Worked Example: A Startup's Documentation Cleanup

Setup: A 12-person engineering team at a B2B SaaS startup has been shipping for two years. Their documentation lives in: three GitHub READMEs (incomplete), a Confluence space (50 pages, half outdated), a Google Drive folder with onboarding notes from 2022, and various Slack pinned messages. A new backend engineer is joining in two weeks.

Their cleanup:

Week one: Two engineers spend four hours on the audit. They produce a list: 6 services × 4 documentation types = 24 document slots. Current state: 9 exist and are mostly accurate, 7 exist and are outdated, 8 don't exist.

Week two: They prioritize the 8 missing documents by the "would block new engineer" test. Four are high priority (setup guides for the two most active services, and the deployment process docs). They assign owners and a one-week deadline.

They adopt one rule for the PR template: "Documentation affected? Updated in this PR?" No other process change.

Six months later: The new engineer onboarded in 3 days instead of the usual 2 weeks. The Confluence space has 60 pages but 55 of them are current (the stale 5 were identified and tagged as "needs update" during the audit). The PR checklist addition has kept the most-trafficked documentation current; the rarely-touched services are still sparse but no longer getting worse.

---

Key Takeaways

1. The Diátaxis framework prevents mixing documentation types: tutorials (learning), how-to guides (task completion), reference (information lookup), and explanation (conceptual understanding) serve different needs and are organized and maintained differently.
2. Documentation belongs where engineers look for it: service-specific docs in the repository; cross-service and process docs in the team wiki; code-level explanations in inline comments — the single-source-of-truth principle prevents duplication and divergence.
3. The PR checklist is the most reliable maintenance intervention: asking "does this change affect documentation?" at the moment of code change is when the engineer is most likely to know and most able to act.
4. The documentation audit converts abstract "improve docs" intent into specific gaps with owners: a 2-hour audit produces a prioritized list of gaps; without this specificity, documentation improvement remains an intention rather than work.
5. Docs as code applies version control, review, and automation to documentation: the same rigor applied to code can be applied to documentation with plain-text files, git history, and CI/CD integration.

---

Conclusion

Organizing technical documentation is a retrieval problem, not a production problem. The goal is that the right document is findable in under a minute by someone who doesn't know where to look — through consistent naming, appropriate location placement, cross-linking, and a single source of truth for each piece of information. Maintenance is a process problem solved by PR checklist items and named ownership. The audit converts the abstract problem into a specific, actionable list. The "docs as code" workflow applies engineering rigor to documentation as a first-class artifact.

Related reading: Web Clipping for Research Papers.