Documenting the user interface

I recently spent an hour explaining to a potential colleague what it was that our team do. I’ve discussed this recently partly in reference to a recent Design Critique podcast but, as this particular person is closer to our business, it was possible for me to dispense with the coffee shop analogy.

Instead I chose to trawl through some of the documentation I produce. Since taking Dan Brown’s tutorial at User Experience 2006 and reading his excellent book I’ve become a bit of a documentation junkie to the point where the documentation is clearly overkill for certain smaller jobs. So I thought I’d take the opportunity to show off some of the styles and approaches I’ve adopted.

I tend to start with personas, which, as any number of user-experience articles will tell you, are a foundation stone for understanding how users interact with a system. This involves defining a group of users (generally from research data), building demographic profiles, and understanding their needs and motivations before sketching out the scenarios in which they might find themselves. I present each of these in a summary page and detail page . I am not a huge fan of using photographs to illustrate personas as I think the audience dwell on any physical appearance, so I have borrowed from Loz Gray’s work and introduced iconographic representations. These have the added benefit of being race-neutral and re-usable for various ages.

Having produced these, the next step in the process is to define a sitemap. The sitemap, such as it is, has a limited lifespan. In the next few years I doubt we will see many produced as the web moves away from individually coded static pages. Sitemaps do a great job of representing hierarchy, taxonomy and the long-view of how things fit together but they don’t really give us much insight into how, for example, a complex dynamic service application or something like Google Maps works. More and more I find myself representing stacks of pages in a sitemap rather than individually referenced HTML documents.

That said, in the absence of producing something more ambiguous, like a conceptual model, they are churned out continuously here at The Company. If I am honest, they are welcome relief for me as I am not a great fan of the chore of creating personas and prefer moving around boxes and arrows. I think this can be seen in the detail of my recent sitemaps, which present a considerable amount of information to the build team, the content developers, and the information architects.

For example, this blow-up detail shows the relationship between pages (connecting lines), their hierarchy (top down), their category (blue background), whether they have had content produced (green circle), where they are hosted (colour of title), their reference number (top left of box) their wireframe type (top right of box) and, of course, their title (centre). In other pages, not shown in this detail, I have used the bottom left corner to indicate whether there is any embedded video on the page.

Granted a sitemap like this has gone through much iteration as the project moves through the design phase toward build (hence there are references to wireframes and content) but to me it shows the level of detail to which one can go whilst maintaining an accessible document. The classic example of which is C. J. Minard's seminal diagramatic map "Napoleon's March to Moscow".

From the early sitemap we can walk the personas and their scenarios through the screens and map their journey. Interchangeably known as user-journeys, task flows, page flows or scenarios, these documents demonstrate how well your information architecture (as seen in the sitemap) works. Again, I borrow here from Loz Gray and use an isometric style that I think promotes a clear view of the journey the user takes. Flat 3D boxes and arrows don’t really inspire or compel stakeholders, if you put up a nice diagram like this it becomes easier for your audience to visualise the journey and the sense of the user being ‘presented’ with screens. I have used this approach for the last five months across static and active sites, allowing clients to visualise everything from amending personal details to clicking through a knowledge store or finding help. With the shape set now firmly embedded in my Visio toolbox I can drag and drop shapes leading left and right, different arrow forms to represent strong, weak and conditional paths, decision points (an isometric diamond is a difficult thing to draw indeed), error points and just about anything the sitemap can show.

In several instances, the barriers between processes have jumped out at me when presenting them in this format. Missing links suddenly seem even more obvious, lengthy diversions and crowded critical paths are quickly spotted and revised.

The final step in my documentation journey is the wireframe. Having experimented recently with the low-fidelity ‘page description diagram’ approach – which to me is like describing the front page of The Times when a blurred photocopy would have been more effective – I have resolved to stick to medium-high fidelity wireframes. In part this is because I’ve always liked the creative construction side of wireframing. I’d feel cheated having gone to great lengths in describing personas, the sitemap and the journey the user takes only to be produce an ambiguous written description of a screen. A well considered wireframe still leaves the designers with more than a colouring-in job. The designers can add visual prominence, alter sizing and positioning and consider complimentary form and colour. What I feel the information architect’s job is to do is to say ‘here’s how the page should function, this is where they should look for x, this is where they will find y and these are the relative levels of prominence’. It is less prescriptive than the building architect’s blueprint but considerably less ambiguous than saying “the room in this house should have three windows, two electricity points, a wooden floor and four brick walls”. So, my wireframes show text placeholders, pseudo-latin text, layout, order, scale, complexity and also contain build or dynamic element-related annotation.

I’m pedantic and fastidious about version control and document referencing. All my documents are peppered with notes about page and document versions, titles, page references, disclaimers (“Wireframes do not represent the final design…”), client names, contact details and relevant key/legends. It is crucial when so much documentation is floating around that we have a clear view of what it does, who did it, for whom and when.

I hope this has been an interesting read, please do get in touch (john at smorgasbord dash design dot co dot uk or in the comments) if you’ve got examples of documents you produce or alternative approaches to this kind of stuff.