Documentation Nobody Reads

Most architecture documentation is written once, read never, and becomes outdated within months. The problem is not documentation itself — it is documentation that does not serve a clear audience with actionable information. At Nexis Limited, we maintain architecture documentation that actually gets used by focusing on high-value, low-maintenance documentation types.

Architecture Decision Records (ADRs)

ADRs document significant technical decisions — why a technology was chosen, why an architecture pattern was selected, or why a tradeoff was made. Each ADR includes:

  • Title: A short description of the decision.
  • Status: Proposed, accepted, deprecated, or superseded.
  • Context: The problem or situation that prompted the decision.
  • Decision: What was decided and why.
  • Consequences: The tradeoffs and implications of the decision.

ADRs are stored in the repository alongside the code. They answer the most common question in software engineering: "Why was this done this way?" New team members read ADRs to understand the reasoning behind the existing architecture without interrogating the original authors.

C4 Architecture Diagrams

The C4 model provides a hierarchy of diagrams at increasing levels of detail:

  • Context diagram: Shows the system and its interactions with external users and systems. Non-technical stakeholders can understand this level.
  • Container diagram: Shows the major technical building blocks — web applications, APIs, databases, message brokers. This is the most useful diagram for developers joining the project.
  • Component diagram: Shows the internal structure of a container — controllers, services, repositories. Useful for developers working within a specific service.
  • Code diagram: Class-level diagrams. Usually auto-generated and rarely maintained manually.

Maintain Context and Container diagrams. Component diagrams are optional. Code diagrams are rarely worth the maintenance cost.

Runbooks

Runbooks document operational procedures — how to deploy, how to rollback, how to respond to specific incidents. They are living documents that on-call engineers reference during incidents. Key runbook content:

  • Step-by-step procedures for common operations.
  • Incident response guides linked from monitoring alerts.
  • Database operation procedures (migration, backup, restore).
  • Environment-specific configuration and access instructions.

API Documentation

API documentation should be auto-generated from code annotations (OpenAPI/Swagger) to avoid drift between documentation and implementation. Supplement auto-generated docs with usage guides, authentication instructions, and example workflows.

Keeping Documentation Alive

  • Documentation as code: Store documentation in the repository, review it in pull requests, and treat it as a first-class artifact.
  • Update triggers: When changing architecture, update the relevant ADR or diagram in the same pull request.
  • Quarterly review: Review and update architecture diagrams quarterly. Delete or archive outdated documentation rather than leaving it to mislead.
  • Assign ownership: Each document has an owner responsible for keeping it current.

What NOT to Document

  • Implementation details that change frequently — the code itself is the best documentation of how it works.
  • Information available elsewhere — do not duplicate framework documentation.
  • Meeting notes (use a separate system for those).

Conclusion

Effective architecture documentation serves specific audiences with actionable information. ADRs explain why decisions were made. C4 diagrams show system structure. Runbooks guide operations. Keep documentation minimal, maintain it alongside code, and delete it when it becomes stale.

Need help documenting your architecture? Our team can audit and create architecture documentation.