This week is the final installment of my three part series on Documenting the design of a web application. Two weeks ago I started this series with Part one: Using Garrett’s Visual Vocabulary to document the Information Architecture. Then last week I followed it up with Part two: Using static HTML mock up screens to document the User Interface and show the User Experience. While both of those methods of documenting the design of a web application are extremely useful, neither are particularly ground breaking (though, as a side note, I’m still amazed by the number of “User Experience designers”, or “Web designers”, etc who don’t know about or use these methods). This week I’ll introduce and explain my third document type; Page state diagrams (which are still not ground breaking, but are a little different to what I’ve seen elsewhere).

So far so good, but something is missing

By this point in an application’s design I have (at least) an Information Architecture overview diagram and a more detailed functional area IA diagram for the area I’m currently working on. As well as these diagrams I have a collection of static HTML pages that show the user journey and User Interface for the functional area. Collectively these add up to a powerful communications tool. However…

With all modern web applications there are some pages that will look different under different circumstances. For example when a user submits a form, but has not completed it correctly it is normal for the form to be redisplayed to the user with an error message explaining what they missed. These types of pages pose a problem when it comes to documenting their design. How do I convey their multiple versions without over complicating the IA diagrams or the static mock ups?

Adding multiple representations of each page to the IA diagrams was not an option for two reasons:

1. the idea of the IA diagram is that there should be one representation of each page of the application; adding multiple representations for the same page would go against this philosophy
2. breaking the philosophical rule wouldn’t be too bad, if it weren’t for the fact that by adding additional representations of each page the IA diagram would become very cluttered, and difficult to understand, which defeats their intended purpose.

Another option would have been to add links or buttons from any page in the static mock ups to the page’s alternative states, after all, each state should be mocked up anyway, and could be linked to. However, again, there are two reasons not to do this:

1. the static mock ups should be as real a representation of the final UI as possible, and having extra links or buttons leading to alternative states of the page would not be realistic, and will distract people when walking through the mock up (“Why would we need three buttons on this form?”, etc)
2. more importantly, the presence of these links / buttons would disrupt the flow of the interaction as users walk through the mock ups, making each process seem complex, convoluted and confusing.

So, with both those options discounted I had to find an alternative way of documenting and explaining Page states to people.

Introducing Page state diagrams

The answer I came up with is the Page state diagram. A single page document (in my case a Visio document) that show three things:

1. which page of the application the diagram is for and how many states it has
2. a screenshot of each state to show how the user will see it
3. an explanation of under which circumstances each state should be displayed.

An example of one of the Page state diagrams I drew up for a page in one of our ProcServe applications is below.

Note that the diagram’s title matches the number and name of each page on the IA diagrams, which also matches the name of the static HTML file so they can all be easily matched up. Also, as hinted at in part 1, on the IA diagrams I highlight any page that has multiple states by adding “#” (where # is the number of states) to the page’s representation, so people know to look for a Page state diagram in the first place.

Summing up

By mapping out all the possible states of a page like this I have a concise, easy to understand document that I can give to our developers so they can see how dynamic aspects of the design should work, and start building them. By combining these diagrams with the Information Architecture diagrams and the static HTML mock ups I have a set of documents that I can use to explain both the high level overview and the low level detailed view of an application’s design. They are a simple way of communicating what can be a very complex design to all the different people involved in a project. And they’re easy to make and maintain. If only all documentation was like this.