Skip to content

Technical Documentation

Technical documentation records the information needed to understand, operate, maintain, recover, or change a website and its supporting systems.

Technical documentation records information needed to understand, operate, maintain, or change a website and its supporting systems.

Useful documentation reduces reliance on individual memory.

What It Can Document

Website documentation might include:

The exact documentation should reflect what another person would realistically need to continue the work.

Documentation vs. Password Storage

Documentation can record:

Hosting credentials are stored in the organization's password manager.

It should not necessarily contain:

Password: hunter2

Secrets are better kept in an appropriate credential-management system.

Documentation explains where and how access works.

README Files

Code repositories commonly use README files to explain the project's purpose and how to work with it.

GitHub recommends repository READMEs for explaining why a project is useful and how people can use or work with it. GitHub Docs: Customizing your repository

Why It Matters

Without documentation, routine questions become archaeology:

  • Where is DNS managed?
  • Which branch deploys production?
  • Why does this plugin exist?
  • Which API key belongs to production?
  • Does anyone know how backups work?
  • Who owns the Stripe account?
  • What happens when this webhook fails?

The website becomes more expensive to change because every future person has to rediscover the system.

Documentation Can Become Technical Debt

Documentation that is wrong can be worse than documentation that is incomplete.

It creates false confidence.

Documentation therefore needs an owner and should be updated when important architectural decisions change.

Common Problems

Common problems include:

  • Documentation written only at launch
  • Credentials stored insecurely
  • Huge documents nobody can scan
  • No record of why a decision was made
  • Setup instructions no longer work
  • Documentation stored in contractor account
  • Important knowledge only in email or chat history

How to Improve

Document the unusual and operationally important parts first.

Prioritize:

  1. Ownership
  2. Architecture
  3. Access
  4. Deployment
  5. Recovery
  6. Integrations
  7. Known risks

Keep instructions close to the system they describe where practical.