In keeping with our values of of radical transparency, self-reliance, and "read it twice", we use documentation to keep track of all the details of a site as it progresses from idea to reality and then into its lifespan under a maintenance retainer.
Related Procedures
The primary goals of the documentation are:
- Provide total clarity for the client on the plan for their site and the features it contains. Suppliment their SOW with a fully detailed description of the project.
- Equip teams taking on the next stage of the project to do their job successfully. This may mean handing off from UX to Visual Design, or from Dev to support, whatever.
The documentation is a “living” document. It should adapt to meet the ne eds of the next team. So if it is updated in UX, it should then be geared towards educating the visual design team on the UX intent and how it may need to change or grow during visual design. If it is written in development, it is geared towards being used to QA the site.
During each phase of our projects, the person responsible for design or dev work should update the documentation, or delegate that responsibility to someone else. This means making changes and clarifications based on decisions made during the prior phase, and preparing the documentation to be used by the next team. The client should review the documentation after each phase to ensure that it is accurate to their understanding of the project. This helps avoid scope disagreements later in the process.
Section Overview
A good structure is:
- Competitive Landscape: Identify other sites the user is likely to visit if they are visiting this site, and how we plan to contrast with them.
- Design Direction: For both UX and visual design, identify what our design approach will be for the site. Is it quirky and fun, or stately and serious? Is it animated, or static?
- Audience Analysis: Who does the site serve? How will it address each of its audiences well?
- Components: What are the general elements of the site (not page-specific), such as headers and footers? How should they work and be designed?
- Pages: For each page of the site, what is its purpose and what should be contained on it?
- Behaviors: What general functionality should be included in the site, such as analytics?
- Technical approach: What CMS will we use, if any? Are there any key third-party code integrations?
If you are executing this procedure after discovery, you should be able to pull in a lot of that stuff from the discovery report.
Section Guidance
Behaviors
For each Page, include a link to the design comp in both mobile and desktop, if you have it. Include the details of what should be on the page and any specific issues to look out for.
Pages
Within each component subsection, include a screenshot of the component along with a list of characteristics it should have. For instance: "The header should always appear small, except on the homepage, where it should be twice the normal height".
Components
Within each section, there should be a sub-section for each aspect of the site that needs to be tested. Here is an example table of contents for one of our checklists:
- Audits. This section will list any and all (design or development) accessibility audits that have been run for the project. This section is more of a historical log than a living document. So, changes should be noted in follow-up documentation rather than as replacement.
- Behaviors. This section include information about general or invisible functionality, like how all accordions should work, or how Google Analytics should work.
- Pages. This section includes information about specific routes on the site, like the About page, Team page, etc.
- Components. This covers elements which appear on most pages, like the header, footer, etc.
Each checklist contains multiple sections related to development, design, or function, but a few sections in particular will especially be of use to the QA engineer:
With the Project Documentation, even someone totally unfamiliar with the project should be able to hop in and start testing it.
In order for a QA person to test a site, they need a checklist to check against. This describes the functionality and qualities of the site, and links to relevant design mockups or documentation.