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:
- properties related to contained controls (i.e. drop down field with these and those values of which that particular one is selected by default)
- 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?
4
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.
2