«
»

4 easy steps for documenting user interface

I was asked today on which best practices exist in documenting user interfaces. Especially with focus on documenting how and where the user interface (GUI) communicates with backend services.

The format I usually use is:

  1. Screenshot
  2. Description
  3. Preconditions
  4. Postconditions

Explanation:

  1. Screenshot of the entire page or content area
  2. Description of the page purpose. Primary action and possible secondary actions on page.
  3. Preconditions: What data must be available for the page to render. Where is data retrieved?
  4. Postconditions: Data that the user enters. Where is data saved? (Could also be data behavioural data: Example measuring if user completes a purchase)

Then repeat for each screen. Sometimes I also need to document variations of each screen. In that way, each page is repeated with the appropriate screenshots.

One big advantage for me is that documentation tend to become fairly brief and concise. My focus is collaboration over documentation, where the shorter is the better.

What are your experiences with documentation of GUI in a format that is short and concise and easy to maintain?

Technorati Tags: , , , , , , ,

This entry was posted by Jesper Rønn-Jensen on Wednesday, November 22nd, 2006 at 11:51 (GMT-1) and is filed under Best of Justaddwater, User Interface. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.

7 Responses to “4 easy steps for documenting user interface”

  1. Rasmus Knippel Says:
    November 22nd, 2006 at 12:47 (GMT-1)

    As I was the asking party I just want to add a couple of lines.

    The problem is, as noted above, that some of the GUI is interacting with various services and systems. What I need is a way to “anchor” a GUI in such a way that I can identify which GUI’s potentially will be affected of a change in the backend services (URL is not an option).

    Looking forward to you input..

  2. Preben Carlsen Says:
    November 22nd, 2006 at 13:25 (GMT-1)

    Depending on the complexity of the GUI, I sometimes uses the model suggested by Jesper, sometimes uses QuickTime to demonstrate and thereby reduces a potential big number of screenshots.

  3. Percy Says:
    November 22nd, 2006 at 17:30 (GMT-1)

    This is a neat way to do the documentation. I wish I’d known about it when I used to do UI evaluations of a product. It seems to be that you’re really cutting it down to the essentials and in doing so you could even find problems that might have been overlooked earlier. Even if you don’t, it’s a nice way to handle the documentation.

  4. Thomas Baekdal Says:
    November 22nd, 2006 at 18:21 (GMT-1)

    Jesper, that is good advice – and a very simply method. I use the method of “whatever-I-can-think-of-documentation”, which is not very good. Maybe I should give your approach a go.

    Rasmus, A good way to see the relation between interface elements and interactions is to make a mind map. Most of the system that I make is modular; meaning the same interaction and interface elements is used in many different scenarios and systems (with an added bonus of creating cross-system consistency).

    Combining Jespers’ method with a mind map could really be interesting.

  5. WebWord » Blog Archive » 4 easy steps for documenting user interface Says:
    November 26th, 2006 at 16:48 (GMT-1)

    […] Short, simple, easy…  […]

  6. fsbrainstorm v4.0 » Blog Archive » 4 Easy Steps for Documenting User Interfaces Says:
    January 22nd, 2007 at 01:12 (GMT-1)

    […] Here are 4 easy steps for documenting user interfaces from justaddwater.dk. In short: […]

  7. 1001 Lists To Read Before You Die | Terabell - technology, law, programming and a laugh Says:
    August 11th, 2007 at 11:40 (GMT-1)

    […] […]