UX Documentation: Why, What and How

Win Your Copy
Win Your Copy

Our three copies of Information Architecture just arrived. Enter to win your copy.

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.

About the Author

Pamela Rodríguez

Pamela Rodríguez is an Interaction & Interface Designer at a mexican usability consultant company. She is a public speaker and a blog writer on topics of web design and user experience. You can reach her on Twitter or visit her LinkedIn profile.


  • Mike Reply

    Great post.

    Can you provide a link to the site referenced in “USABILITY TESTING ON PROTOTYPES”? Thanks.

  • Franz Reply

    Nice article, something that needs to be done way more often.
    I think you could have included persona life cycle documentation as well.

  • Lisanne van Hooff Reply

    Hi Pamela,

    Nice overview and reminder of what we should keep in mind! Thanks for giving a clear overview including helpful links. We can use it as a reminder as well.

    I noticed you are writing just a little on including information like user feedback and development decisions. Although your first point in the article is about why the documentation matters so much: “It’ll help you constantly improve your working process and, gradually, your results.”

    I would like to add something to the story;

    User feedback and development decisions are very important for the ongoing project. And I do believe you can learn from it, but some project deliveries are telling you just as much as your own opinion on them.

    If you do want to improve your work (process and results) I think you need to put a little more afford into it.

    Learning points can be about a lot of things, e.g., Ways of collaboration within the project team which gave great energy to the team members or maybe it was just really inefficient. Or about a diagram which a client totally misunderstood…

    You can write it down and give it a go. But to take a second and talk about a (or all those) lesson(s) learned within the project team or a peer group can help you to keep it in mind and even make you put it into practice the next time.

    Kind regards, Lisanne van Hooff

  • Neil Murphy Reply

    I agree with this and its a good rehash of 30 year old ideas brought into the modern web world.

  • Rob Reply

    Version control information (e.g. changes since last drop), Client feedback associated with changes, developer feedback, client sign-off should also be included on UX documents where they are part of a program of works or extend beyond a short duration. This information is vital to the maintenance of the document and the ellaboration of “how we got were we are today”.

Leave a Comment on This Article