Skip to content

The Importance of Documentation

Documentation That Actually Helps

We've all been there: you inherit a project with docs that are either missing, outdated, or flat-out wrong. It's frustrating, time-consuming, and completely avoidable.

Good documentation isn't nice-to-have - it's essential. Poor docs lead to operational nightmares, frustrated developers, and services that nobody wants to touch.

The cardinal rule: Stale documentation is worse than no documentation. If the docs lie to you, you'll waste time following bad instructions. If there are no docs, at least you know to read the code.

That's why the README gets updated with every change to the project. Not eventually. Not when you remember. Every time.

Project README Requirements

Every project gets a README that follows this structure. No exceptions.

# Project Name

> **Maturity Level**: [Emerging|Basic|Mature] - (a short sentence fragment for context)
>
> - **Emerging**: Prototype, not production-ready, expect breaking changes
> - **Basic**: Production-ready but actively evolving, expect minor version changes
> - **Mature**: Stable, battle-tested, changes are rare

---

A sentence describing the project. Two at most.

## Usage

## How it works

## Key Considerations

## Development Considerations

### Quick Start

### Building & running

### Testing

### Versioning

README Guidelines

Follow these rules to keep READMEs useful:

  • No emojis - They tend to clutter things up and don't add much for a technical audience (checkboxes are fine)
  • Working links only - Test every link before committing. Broken links destroy credibility
  • Never duplicate docs - Reference other docs, don't copy-paste them. DRY applies to documentation too
  • No file tree diagrams - They're useless and become outdated instantly
  • Explain versioning - Document how the project is versioned (usually git tags)
  • No workstation setup instructions - Include version requirements, not "how to install Node.js"
  • Write for the reader - What do they actually need to know?
  • Most important stuff first - Lead with usage, bury the implementation details
  • Be specific - "Configure the database" doesn't help anyone. "Set the DATABASE_URL environment variable" is helpful
  • Show, don't just tell - Include examples. A code snippet is worth a thousand words

Operational Documentation

Regular maintenance and operational tasks live in our team's OpsBook (operational runbook containing maintenance procedures and incident response guides). We don't rely on people remembering to do these tasks - each one has a Jira Automation that creates tickets on schedule.

Examples of operational tasks:

  • Checking logs for anomalies
  • Renewing certificates before they expire
  • Rotating API keys for third-party services
  • Reviewing access permissions

If it needs to happen regularly, it goes in the OpsBook with automation.

Documentation Types & When to Use Them

Different documentation serves different purposes. Use the right tool for the job.

README.md

  • When to use: Every project, no exceptions
  • What goes in it: Project overview, usage instructions, development setup
  • Who it's for: Developers, operators, anyone who needs to use or work on the project

CHANGELOG.md

  • When to use: Projects with semantic version releases (v1.0.0, v1.2.3, etc.). Projects without versioned releases (internal scripts, one-off tools) may use commit history instead
  • What goes in it: What changed between versions (follow Keep a Changelog)
  • Who it's for: Users upgrading versions, maintainers tracking history

Confluence Pages

  • When to use: Process docs, architecture decisions, team knowledge, OpsBooks
  • What goes in it: How we work, why we made specific decisions, operational procedures
  • Who it's for: Team members, stakeholders, future team members

Runbooks

  • When to use: Production services that require operational support
  • What goes in it: Troubleshooting guides, emergency procedures, monitoring dashboards
  • Who it's for: On-call engineers, operations team, anyone responding to incidents

← Previous: Deliver Solutions that Work | ↑ Back to Home | Next: Managing Our Source →