Documentation Is a Product Feature

Good documentation reduces support tickets, accelerates onboarding, prevents production incidents, and enables team scaling. Poor or missing documentation creates knowledge silos, slows development, and increases the bus factor. At Nexis Limited, documentation is part of the definition of done for every feature.

Types of Documentation

README

Every repository must have a README that answers: What does this project do? How do I set it up? How do I run it? How do I deploy it? How do I contribute? A developer should be able to clone the repository and have a running development environment within 15 minutes by following the README. If they cannot, the README is incomplete.

API Documentation

API documentation should include every endpoint with request/response examples, authentication requirements, error codes, and rate limits. Use OpenAPI (Swagger) for REST APIs and auto-generate documentation from the spec. Include runnable examples — developers will copy-paste your examples before reading your prose.

Architecture Decision Records (ADRs)

ADRs document significant architectural decisions — what decision was made, why, what alternatives were considered, and what the consequences are. Store ADRs in the repository alongside the code they describe. When a new engineer asks "why is this designed this way?", point them to the ADR instead of relying on oral history.

Runbooks

Runbooks document how to handle operational scenarios — deployments, incident response, database migrations, and common failure modes. A runbook should be specific enough that an on-call engineer encountering the scenario for the first time can follow it successfully. Include commands, expected outputs, and decision points.

Onboarding Guides

Document the setup process for new team members — tools to install, repositories to clone, access to request, and key concepts to understand. Maintain this document as a living guide that new hires update as they onboard, fixing gaps and outdated steps.

Writing Principles

Write for the Reader

Documentation serves the reader, not the writer. Consider who will read it — new developers, experienced engineers, DevOps, or non-technical stakeholders — and adjust the level of detail and assumed knowledge accordingly.

Lead with the Most Important Information

Put the key information first. A developer looking up an API endpoint wants the URL, method, and parameters immediately — not three paragraphs of context about why the endpoint exists. Use headings, tables, and code blocks for scannability.

Include Examples

Every API endpoint, configuration option, and code pattern should include a concrete example. Examples are more effective than descriptions. Show a complete, working request/response pair, not abstract syntax diagrams. Test your examples to verify they work.

Keep It Current

Outdated documentation is worse than no documentation — it wastes time and destroys trust. Treat documentation updates as part of code changes. If you change an API, update the API docs in the same pull request. Review documentation during code reviews.

Documentation-as-Code

  • Store documentation in the repository alongside the code it describes.
  • Use Markdown for prose, OpenAPI for APIs, and Mermaid or PlantUML for diagrams.
  • Review documentation changes in pull requests alongside code changes.
  • Auto-generate documentation from code where possible (TypeDoc, Javadoc, Sphinx).
  • Deploy documentation with CI/CD to a documentation site (Docusaurus, GitBook, VitePress).

Measuring Documentation Quality

  • Track time-to-first-successful-API-call for new API consumers.
  • Monitor documentation page views and search queries to identify gaps.
  • Survey developers on documentation usefulness during onboarding.
  • Track support tickets that could have been answered by documentation.

Conclusion

Documentation is not optional — it is infrastructure that enables your team to work effectively. Invest in README files, API documentation, ADRs, and runbooks. Write for the reader, include examples, and keep documentation current. The time invested in documentation pays dividends in reduced confusion, faster onboarding, and fewer production incidents.

Building your engineering culture? Our team can help establish documentation practices.