Overview

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.

<aside> ☝ 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.

</aside>

🏅 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.