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 or New Build. We should then keep it updated any time we change the site.Tune-Up
One primary function of Site Documentation is . QA testers will refer to the documentation whenever they test the site. Therefore it is important that it always be up to date.QA
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.