Miskeeto

Usable documentation

A miskeeto byte from Robert Hoekman, Jr. Posted on November 21st, 2008

Good design doesn’t end at the sites and applications we work on. To be truly successful, design thinking needs to permeate every aspect of a project, including process, communication, project management, and yes, deliverables.

When I created the official Miskeeto usability review template, I knew the document itself had to be as self-evident and useful as anything I recommend the client do to improve its site — otherwise, I’d surely get lots of return questions for what should be a short and concise process. To create a usable review document, I needed to address a couple of key requirements:

• The client should be able to quickly understand which design elements are problematic and why
• The review should be focused entirely on tangible takeaways that can not only be applied to the current state of a design, but also to future iterations and additions

Here’s what I did.

First, I created a cover page that makes the document purpose clear. It includes the client’s name, the project title, and the date the review was last modified, and a byline for whoever created the review.

Second, I added a page for more specific information, such as the name of my primary contact within the client company and that person’s email address, along with a description of the methods used for the review.

Next, I included a table of contents (TOC). Obvious, yes, but I also made it a rule that all headings in the document would be written as calls to action so that the TOC read like a to-do list of actionable recommendations, and then linked each TOC item to its corresponding section in the report. For example, “Add inline validation to registration form” tells the reader exactly what I think should be done, as well as what problem will identified and explained in that section.

To make the recommendations easy to spot while scanning the document, I set up a style for sub-headings to point them out within each section, and excluded these labels from the TOC.

Finally, I added a placeholder for a wireframe or sketch within each section so, when needed, I could create an image that illustrates the recommendations.

The result is a review document that is quite usable unto itself. Clients can simply scan the TOC for a checklist of action items, click a TOC heading to jump straight to the details, and easily pick out the list of detailed recommendations (often including wireframes) under each section.

Miskeeto clients have had very positive things to say about these reviews, and we believe it’s in part because of this template.

Design affects, well, everything. Applying good design to your deliverables ensures your projects will go much more smoothly.

Want to see an example?

Take a look! (PDF, 88kb)

(Note: Actual reviews are much longer!)