Site Documentation


To manage a website effectively, you have to write everything down. For every site we manage, we maintain a document within the that represents the site.

The document should be created when we first touch the site, whether in a 🏢New Build or 👩‍🔧Tune-Up. We should then keep it updated any time we change the site.

One primary function of Site Documentation is 🔍QA. QA testers will refer to the documentation whenever they test the site. Therefore it is important that it always be up to date.

Note: Site Documentation is not the same as a README file, which would contain instructions for running a repo locally, and other details. It is more of a contextual document.

🏅 Principles

  • Not too much. Documentation can be hard to maintain and read when it is too detailed.
  • Not too little. When we don’t provide enough information, it can be hard to QA a site and know if something is working properly.

📏 Rules

✅ Do…

  • Include information on every site page and key component
  • Include background information on invisible site aspects like analytics, integrations, etc
  • Provide general information about the technical approach we use for the site

🚫 Don’t…

  • Move documentation to another app/location unless there is a specific reason (ex. we keep one site documentation file in a client Confluence account)

Typical Outline

  • Components: Describes general site elements like headers and footers.
  • Pages: Details the purpose and content of each site page.
  • Behaviors: Lists site functionalities like analytics.
  • Technical Approach: Specifies CMS and third-party integrations.

The documentation, complete with checklists and design mockups, enables even newcomers to effectively test a site.