Documenting the design of a web application -Part one: Using Garrett’s Visual Vocabulary to document the Information Architecture
For the past two and a half years I have been working in the world of User Experience and web interface design. Most of that time was spent designing interfaces for web applications for different clients while working at PA Consulting, since joining the team at ProcServe I have been doing the same kind of work for our own applications.
Over this time, I have tried, dismissed, adopted and adapted many different ways of documenting and communicating my designs to various groups of people; clients, managers, developers, other interface designers, etc. After this trial and error approach, I’ve settled on using a combination of three main document types; Information Architecture diagrams, Static HTML mock up screens, and Page State Diagrams.
Over the coming weeks I plan on explaining each of these in tern, starting this week with Information Architecture diagrams.
Showing the big picture on one single sheet of paper
One of the biggest challenges I face daily when talking to people about an application is getting them to understand the scope of it; what are the various areas of functionality this application will offer and how do they relate to one another?
The best way (I’ve found) of solving this problem is by drawing up an Information Architecture diagram for the entire application.
Using Garrett’s Visual Vocabulary for Information Architecture I draw up a high-level overview of the entire application. Each functional area is mapped out with enough detail to show what functions are available in each area, along with who can access them. Below is an old version of the IA diagram we use at ProcServe to map out our buyer portal (this was my first attempt at mapping out the portal, at time of writing we’re now on version 10 of this – it’s evolved hugely).
This diagram shows two major areas of the portal; the public facing area and the secure, registered users only area (shown as the area with a conditional, red border). To move from the public area to the secure area our users have to login (page 10) and pass through the logic represented at decision point (a). I’ll not go into the detail of all the symbols and shapes here (they are explained at Garrett’s site) but I will explain some of the additional bits that I add to my diagrams.
Firstly I number each page. I do this not only on the diagrams, but also when naming the HTML documents that I build as mock ups later on. This makes it simple for developers to match up the right HTML with the right page.
Secondly I add an “x2”, “x3”, etc to any page that has more than one “state” – more on this in the article on Page State Diagrams.
It is also important to note a couple of things about these overview diagrams in general:
- These diagrams should fit on one sheet of paper when printed (most of mine end up on A3 sheets, as this one did in later versions) to make them simple to follow.
- These diagrams are not site maps, and do not represent the navigation structure of the application, they only represent the logical relationship between areas (for example on this portal you can move from the “About us” page (06) to the “News” page (03) without going to the “Homepage” (01) first).
- These diagrams are rarely “finished”, that is they are almost constantly being updated and tweaked as a project progresses. (Using place holders to represent functionality that has yet to be thought about is actually a great way to get a feel for the effort required to complete the design.)
There is no fixed rule for the level of detail that should be represented. It’s all about what is needed to get enough of an understanding of what the application will do, not the detail of how it will do it.
Documenting the detail
When it comes to documenting the flow and detail of each functional area I draw up a separate diagram for each one. These more detailed diagrams are used to show the logic and work flow of each function. While the overview document is mainly used to communicate with management and clients, the detailed diagrams are used more with the developers who will build the functionality for real. Below is the diagram we use for our User Management area of functionality of the system administration section of our portal at ProcServe (not shown in the first diagram).
Again it’s important to note:
- These diagrams should still fit on one sheet of paper, in most cases A4 will do.
- These detailed diagrams should include details about how errors and the like are handled.
- These should be as detailed as possible to allow developers to build the functionality described with no room for misinterpretation.
Time and time again these sets of diagrams for each project have proven extremely useful and effective. Clients and management can get a quick understanding of what they are getting. Developers can understand firstly where what they are working on fits in with the bigger picture and secondly how the bit they’re building should work. Designers (including me) get to see how many pages will be needed, how to fit them all together and where there are common features and concepts.
Overall a few simple, one page diagrams allow me to convey a vast amount of information, to a diverse group of people, with minimal effort. My kind of documentation.