UX Documentation: Why, What and How

December 14th, 2010
Published on
December 14th, 2010

Many people don’t see the importance of archiving what transpired during a project. Either that, or they treat the documentation process as a simple compilation of all the deliverables generated. In order to truly learn from their mistakes, though, designers must give more consideration to narrative documentation.

Documentation doesn’t have to be a dirty word, nor does it have to comprise a 500-page document. Instead, it helps tell a project’s story.

Why does it matter so much?

But before we dive in, some of you might wonder why document at all? Well, a number of reasons:

  • Future reference. Be they examples of something we did right or something we shouldn’t do again, documentation of any kind affords a permanent record of what happened. It aids reflection and helps us constantly improve our process and, gradually, our results.
  • Organizing ideas. What was done? When was it done? And how much of it was done? It’s easier to maintain order in a project by referencing documentation.
  • Ramping up new team members. Providing new team members with documentation gives them an idea of the project and its process-to-date. This won’t eliminate your need for a formal introduction, of course, but it will curtail unnecessary conversations.
  • Selling new projects It’s much more pragmatic (and realistic) to sell clients a design process than to sell them a website itself. Documentation is a very good tool in this regard.

What does documentation include?

What constitues documentation actually depends on the type and length of a project. That said, consider a hypothetical project, started from scratch, that eventually developed into a website. Its documentation might include the following:


The introduction, or “brief,” contextualizes a project, providing answers the following questions:

  • Who’s the client?
  • What’s objective?
  • What’s the vision?

Identified users

Even if they’re just guesses, all projects have personas. By eventually maturing them, we support later stages in the design process.

Content requirements

What does the website offer its users? Content requirements can either be see as as a checklist or a strategy unto itself.


What will we do to meet the previously established requirements?.Independent consultant and speaker Stephen Anderson, introduces personality quirks by way of cards, for example.

Information Architecture

A website’s information architecture facilitates understanding. Jesse James Garrett proposes using a visual vocabulary to get designers and their clients to speak the same language.


Interactions are typically documented by way of prototypes or wireframes. They might include basic error notification, success notification, link behaviour, drag and drop interaction behaviour, among others. Clearly indicate feedback on each interaction diagram.


Navigation is an oft-discussed topic. Hagan Rivers goes so far as to diagram entire systems: in a mindmap

Hogan Rivers considers an application on itself. Its objective is to take you to the right screen.

Hagan Rivers

Regardless of how we approach it, navigation is often made more clear when it’s visualized.

Concept designs and prototypes

While sketches and other low-fidelity deliverables often show rejected ideas, they illustrate our thought process.

Usability testing on prototypes

A heatmap of an eye-tracking study.

Testing documentation can be as lightweight as final results and statistics. They may also include the scripts used to lead focus groups or personal interviews. If eye-tracking or mouse-tracking was involved, a heatmap can quickly summarize results.


Development decisions are often made based upon previous documentation and research. Documenting the technologies used and the functionality required helps ensure consensus.

Style guidelines and patterns

Style specifications – concerning colors, images, and other content – should be well established. in order to serve as a guide throughout the development process to maintain the visual design standards.

To sum up

Even if we don’t generate formal documentation for every project we work on, the right amount of documentation helps us order the chaos generated by our creative endeavors.