5

I'm writing documentation for some interactive Ajax user interface but instead of writing everything in words I would rather provide diagrams that are faster consumed than whole paragraphs of text. I did provide page navigation flow diagram but that's very high level before you drill down to individual pages and their inner workings.

Example

Suppose I have to document a typical search panel:

  • is collapsed by default and can be expanded on click
  • has basic search fields that provide basic search criteria over my model entity
  • has advanced fields as well that show when one clicks a particular link which expands search with additional fields
  • has two actions Search and Reset that are pretty much self explanatory, but have particular behaviours attached to them

I know you will say that this already is documentation, but it's usually not this simple and trivial. Search panel is just an example.

I can see that most of my interfaces (or interface components) need two types of documentation:

  1. properties related to contained controls (i.e. drop down field with these and those values of which that particular one is selected by default)
  2. actions and behaviours that describe what happens when user interacts with controls related to those properties

What would be the best diagram or documentation format to describe these kind of interactive interfaces so that it's easy and quick to consume by implementers?

Improve this question
4
  • 1
    Considered video recordings?
    – user1249
    Commented Aug 22, 2012 at 16:52
  • If parts of the UI are reusable, document them in terms of their general layout and behavior. Then, simply state that a particular page has such and such a general control, perhaps with a few specific "tweaks" (like the control being in a collapsible div when it might not otherwise). This is how the implementers will likely think of the design anyway; anything they can encapsulate and reuse, they will.
    – KeithS
    Commented Aug 22, 2012 at 16:59
  • @ThorbjørnRavnAndersen: That's a good idea but... Videos of what? Me explaining the whole interface? Anyway... It has to be printable.
    – Robert Koritnik
    Commented Aug 22, 2012 at 17:05
  • Write to your audience! For me, Screen Shots with description of the interesting bits.
    – Paul
    Commented Aug 22, 2012 at 20:08

1 Answer 1

Reset to default
6

The best documentation I've been given to implement was drawn as wireframes with notes. Each page of the documentation was one wireframe with as many notes as necessary. Each state of any element that needed further explanation spawned another page. For example, a standard drop-down is obvious, but an expanding menu would get notes about sliding effects and what other page of the document it goes to on click of each element.

Advantages of this type of document:

  • It can include as much or as little detail as you like.
  • It can be very helpful to non-developers. Some I've seen included margin spacing, etc. for the designers and an appendix for color choices.

Disadvantages:

  • It can be cumbersome - potentially many document pages to explain a single web page
  • Not visually automated, as a prototype or slide show might be

I'll add this was the preferred style for at least a few user interface experts I've worked with.

Improve this answer
2
  • I'm not a big MS fan normally, but my wife's team really likes MS wireframes microsoft.com/expression/resources/solutions.aspx
    – Paul
    Commented Aug 22, 2012 at 20:10
  • Balsamiq do a nice mock up app. I use that a lot. Also, from Microsoft in VS2012 now you can use Powerpoint to mock up apps and import that into TFS (haven't tried it, don't know what it produces).
    – Ian
    Commented Aug 22, 2012 at 22:27

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.