Engineering Documentation That Gets Read

Most engineering documentation is never read. It’s written once, becomes outdated, and sits in a wiki graveyard. Good documentation is different—it’s maintained, discoverable, and actually helps people do their jobs.

Here’s how to create documentation that gets used.

Why Documentation Fails

Common Problems

documentation_failures:
  not_discoverable:
    - Scattered across tools
    - No search or bad search
    - Unclear naming
    - No entry points

  outdated:
    - Written once, never updated
    - Contradicts current reality
    - No ownership
    - Creates confusion

  wrong_level:
    - Too detailed (can't see the forest)
    - Too vague (can't do anything)
    - Wrong audience
    - Missing context

  poor_quality:
    - Copy-pasted without thought
    - Missing steps
    - Assumes knowledge reader doesn't have
    - No examples

Documentation Types

The Documentation Quadrant

                    Learning ──────────────────► Working
                         │                            │
              ┌──────────┴──────────┐    ┌───────────┴───────────┐
              │                     │    │                       │
   Practical  │     TUTORIALS       │    │      HOW-TO GUIDES    │
              │   Learning-oriented │    │   Problem-oriented    │
              │   Follow steps      │    │   Achieve a goal      │
              │                     │    │                       │
              └──────────┬──────────┘    └───────────┬───────────┘
                         │                            │
              ┌──────────┴──────────┐    ┌───────────┴───────────┐
              │                     │    │                       │
  Theoretical │   EXPLANATIONS      │    │      REFERENCE        │
              │  Understanding      │    │   Information         │
              │  Background, why    │    │   API docs, specs     │
              │                     │    │                       │
              └─────────────────────┘    └───────────────────────┘

  From: Divio documentation system

When to Write What

documentation_types:
  tutorials:
    purpose: Get started, learn by doing
    audience: Newcomers
    example: "Getting started with our API"
    approach: Hand-holding, explain everything

  how_to_guides:
    purpose: Accomplish specific tasks
    audience: Users with basic knowledge
    example: "How to deploy to production"
    approach: Assume context, focus on goal

  explanations:
    purpose: Understand concepts
    audience: Anyone needing background
    example: "How our authentication system works"
    approach: Big picture, why decisions were made

  reference:
    purpose: Look up specific information
    audience: Users who know what they need
    example: "API endpoint documentation"
    approach: Complete, accurate, well-organized

Writing Effective Docs

Structure

good_structure:
  start_with_why:
    - What problem does this solve?
    - Who is this for?
    - When would you need this?

  provide_context:
    - Prerequisites
    - What you'll end up with
    - Time estimate

  clear_steps:
    - Numbered for procedures
    - One action per step
    - Verifiable results

  include_examples:
    - Real code, not pseudocode
    - Copy-pasteable
    - Explain what it does

  anticipate_problems:
    - Common errors
    - Troubleshooting section
    - What to do if stuck

Example: Good How-To Guide

# How to Set Up Local Development

## Overview
This guide walks you through setting up the development environment
on your local machine. By the end, you'll be able to run and test
the application locally.

**Time required:** 30 minutes
**Prerequisites:** Git, Docker, Node.js 18+

## Steps

### 1. Clone the Repository
```bash
git clone https://github.com/company/app.git
cd app

2. Install Dependencies

npm install

You should see output ending with “added X packages”.

3. Configure Environment

Copy the example environment file:

cp .env.example .env

Edit .env and set:

DATABASE_URL: Your local PostgreSQL URL
API_KEY: Get from the developer portal

4. Start Services

docker-compose up -d
npm run dev

Open http://localhost:3000 — you should see the login page.

Troubleshooting

“Port 3000 already in use”

Another process is using port 3000. Either:

Stop the other process: lsof -ti:3000 | xargs kill
Or use a different port: PORT=3001 npm run dev

Database connection errors

Ensure PostgreSQL is running:

docker-compose ps

Next Steps


## Keeping Docs Current

### Ownership

```yaml
documentation_ownership:
  assign_owners:
    - Every doc has an owner
    - Owner responsible for accuracy
    - Owner doesn't have to write everything
    - Ownership reviewed quarterly

  ownership_by_area:
    - API docs: API team
    - Deployment guides: Platform team
    - Architecture: Engineering leads
    - Onboarding: HR + Engineering

  not_owned:
    - Document languishes
    - Nobody updates
    - Becomes harmful

Maintenance Practices

maintenance_practices:
  regular_review:
    - Quarterly doc review
    - Check for outdated content
    - Remove stale docs

  triggered_updates:
    - System change → update docs
    - Question asked repeatedly → add to docs
    - Bug caused by doc gap → fix doc

  automation:
    - Linting for broken links
    - CI checks for doc changes with code
    - Automated reminders for review

  new_hire_test:
    - New hires use docs
    - They report gaps
    - Docs improve continuously

Docs as Code

docs_as_code:
  benefits:
    - Version controlled
    - Review process (PRs)
    - Same workflow as code
    - CI/CD for docs

  tools:
    - Markdown in repo
    - Static site generators (Docusaurus, MkDocs)
    - GitBook, Notion (less "as code")

  practices:
    - Docs in same repo as code
    - PR requires doc update for features
    - Automated link checking
    - Preview environments

Discoverability

Organization

organization_principles:
  clear_hierarchy:
    - Logical categories
    - Consistent structure
    - Not too deep

  entry_points:
    - Landing page with navigation
    - "Start here" for newcomers
    - Quick links to common tasks

  naming:
    - Descriptive titles
    - Consistent conventions
    - Task-oriented ("How to..." not "Guide about...")

Search

search_optimization:
  good_search:
    - Fast
    - Tolerant of typos
    - Shows relevant snippets

  content_optimization:
    - Good titles (searched first)
    - Headers match queries
    - Include synonyms
    - Natural language

Measuring Effectiveness

documentation_metrics:
  quantitative:
    - Page views
    - Search queries (what are people looking for?)
    - Time on page
    - Bounce rate

  qualitative:
    - Feedback mechanisms
    - Support ticket correlation
    - Interview users

  proxy_metrics:
    - Onboarding time
    - Support tickets on documented topics
    - Questions in Slack about documented things

Key Takeaways

Documentation fails because it’s outdated, undiscoverable, or wrong level
Four types: tutorials, how-to guides, explanations, reference
Structure matters: start with why, provide context, include examples
Every doc needs an owner responsible for accuracy
Treat docs as code: version control, PRs, CI
Make docs discoverable: good organization, good search
New hires are your best documentation testers
Remove outdated docs—they’re worse than no docs
Measure effectiveness: views, search queries, feedback
Require doc updates with feature changes

Documentation is a product. Treat it like one.