Documentation Best Practices in Software Projects

Why Most Docs Fail

They're written once, never reviewed, and immediately drift from the code. Developers stop trusting them; readers stop reading them. The fix isn't "write more docs." It's "design docs as a system."

The Diataxis Framework

Four kinds of documentation, each with a different purpose:

• Tutorials — learning-oriented, take the reader by the hand

• How-to guides — task-oriented, "how do I do X"

• Reference — information-oriented, dense and complete

• Explanation — understanding-oriented, the "why"

Confusing them produces docs that don't serve anyone. A reference page disguised as a tutorial frustrates beginners and irritates experts.

Architectural Decision Records (ADRs)

Short, dated documents capturing a single decision: context, the choices considered, the choice made, the consequences. Stored in the repo, reviewed in PRs.

Benefits:

• Future engineers understand why something is the way it is

• Decisions are easier to revisit deliberately rather than redebated ad hoc

• New hires onboard faster

A good ADR fits on one page.

README-First Development

Write the README before the code. If you can't explain what you're building, you don't know what you're building yet. Comes from the open-source world; works equally well internally.

Minimum useful README:

• What this is, in two sentences

• Quick start

• How to run tests

• How to deploy

• Where the deeper docs live

• How to contribute

Living Documentation

Docs that live next to code and update with code:

• API docs generated from OpenAPI / type definitions

• Database schema docs auto-generated from migrations

• Runbooks in the repo, exercised in game days

• Examples that are also tests

If the docs aren't auto-checked, they will go stale.

What to Document and What to Skip

Document:

• Architecture overviews and system context

• Cross-cutting concerns (auth, logging, deployments)

• Onboarding paths

• Domain language and key invariants

• Decisions and trade-offs (ADRs)

• Runbooks for common production issues

Skip:

• Anything well-named code already says

• Tutorials that copy framework docs

• "Comprehensive" specs nobody reads

Tooling

• MkDocs / Docusaurus / Astro Starlight for browsable sites

• OpenAPI / TypeDoc / Sphinx for generated reference

• C4 model + Structurizr / Mermaid for architecture diagrams

• ADR tools for decision capture (e.g. log4brains)

The Bottom Line

Good documentation is a system, not a sprint. Pick a framework, automate what can be automated, and review docs the same way you review code.

*We help teams build docs that engineers actually read — and keep current. Talk to us →*