Write Documentation


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 project as it progresses from idea to reality and then into its lifespan under our support department.

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 needs 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, we have a todo to update the documentation. 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.

Example Output

Note that our format has shifted over time and may not reflect the current standard. Good examples to review are APC and Melfast.

Prior to 2020, we did separate "Discovery Report" or "Audit Report" documents as the final handoff deliverable from Discovery. We often would need to later translate these into documentation, so we determined that we could streamline the process by focusing on one "living" document throughout the project lifecycle. This means that the final Documentation includes more general background infomation about the client and the brand, which is great because future staff and the support department can get up to speed easily on the nature of the client’s business and their strategy in addition to the site itself.

Who can do this

The documentation should be written first during discovery. Anyone who is central to the discovery process can write it, and many members of the team should contribute. Each discovery team should appoint a lead author to be accountable for it, and that author should collaborate with other specialists to fill in various aspects.

What you need

  • Full understanding of the project as agreed during the sales process and discussed with the client throughout the discovery process


Create the document

Go to the documentation database and click "New > Standard Project". This gives you a basic framework to start from which you will need to adapt to the current situation.

Describe the project

Within "Overview", write a substantial description of the project. This should be 200-300 words. Quickly describe the client and what we are trying to achieve for them. Say why we have made some of our key decisions, and what makes this different from our other sites. Identify the client’s key goals with the site and explain how we plan to accomplish them.

Add metadata

At the top of the document there are sub-fields for lots of different kinds of metadata. During discovery you will have very little of this information. Add what you have.

Add additional sections

Depending on the project status you will want to add various kinds of information to fill out the documentation.

If you are doing discovery, 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?

For each screen in your wireframes, there is likely at least one piece of important information that is not implicit. For instance, on a homepage with a slideshow, does the slideshow auto-advance? How fast? On a search page, what should happen while the results refresh? Should it show a loading icon? Or fade out and back in? Make sure that all implicit knowledge is written. This ensures that the client has been informed of all these little details now and needs to accept them or push back. Our developers will refer to this document first before making their own choices, so we need to make sure this is totally solid.

As a project progresses, speculative sections should be replaced with real information. For example, instead of focusing on design direction after design is complete, you can refer to the comps. The design direction is still nice to know, but it requires less explanation since the comps can do the talking. As the project progresses, the documentation should start to include "Checklists" for the QA team to test the final site.