Indolering.com

Today I am going to talk about a typical users, how they learn, and the principals of minimalist documentation.  If you want to skip the fluff, head to the minimalist style guidelines for Ubiquity’s documentation.

Reasoning

(skip this if your not a psych geek ; )

Albert Bandura defined three cognitive prerequisites to learning:

1. Motivation
2. Attention
3. Retention

Tutorials and other traditional documentation which strive to give conceptual overviews are the best way to learn. Volumes of psychological research prove that the thorough processing prompted by a conceptual overview improves retention and performance.

However, the typical setting for traditional psychological tests of learning guarantee both motivation and attention -such as work training. Web browsers are a glass pane- their purpose is to deliver content, their utility invisible, their new features just smudges on the glass, obscuring the view.

Watching professors at school is a lesson on how people interact with FireFox and obstructions to their goals. If FireFox doesn’t start immediately they become flustered and switch to IE. If FireFox asks to apply an update s/he quickly clicking “cancel” to whatever pops up. They are trying to teach a class, not learn new skills or perform maintenance!

Even in my usability studies, when participants actually have the goal of learning the interface, they are seemingly incapable of reading the documentation. Only one user, who was very insecure about his technological prowess, methodically read the tutorial.  After that, his performance was great. However, that means that the tutorial only works for 10% of a dedicated user-base, while 90% are left in the dark.

The test was a bit skewed; users were artificially motivated, but they also had the discoverability problem which Taskfox will fix, but many still had either poor performance or didn’t value the functionality that Ubiquity added.

So what do we do about this? The most important area is the auto-suggest, it must be magical. I have some ideas on how to add to that, but first some lower-level stuff must be fixed.  The most boring, but essential topic, is how we configure our documentation.

About Minimalist Documentation

The minimalist documentation style, as outlined by Carroll in The Minimal Manual, shows massive improvements in real-world tests where motivation is not guaranteed.  It has subsequently become the dominant paradigm in the technical communication field.  The overall guiding principals of this movement are:

1. Procedural Instruction
2. Minimal Wording
3. Error Recovery
4. Guided Discovery

Procedural Instruction

By focusing on procedural, task based instruction, minimalist documentation caters to how users naturally browse documentation and think about their problems.

Users interaction with documentation occurs when they are inhibited in performing a task.  When users to kill the paper clip, they do not take a tutorial on how to use word or read from the beginning of the manual- they skip to the “paper clip” chapter hoping to find something about turning it off.

Thus minimalist documentation is focused on examples of tasks, there is no attempt to teach the underlying models of operation.  Real users are trying to do something, not understand the grand scheme of things.

Secondly, minimalist documentation is as non-sequential as possible. Each example is independent of the previous example, requiring no knowledge that the user likely skipping anyway.

Minimal Wording

Minimalist documentation attempts to cut down the thicket of prose obstructing the users view of a potential solution.  Users are skimming, facilitate that by leaving only the most essential wording, writing inverted pyramid style, breaking rules of grammar if it increases clarity, and bolding key verbs is used to help users pick out important information.

Error Recovery

Attempt to provide clear checkpoints and examples so a user can make sure that they have carried out the example correctly. Screenshots should crop non-relevant information (unless it visually orients the user) and emphasize important areas.

Guided Discovery

Ubiquity guides users to the functions that they want, and keeps the unnecessary ones hidden from view via it’s auto-suggest.  I will offer some suggestions on how to improve auto-suggest in a more automated way in Part 3.

Read (the much better, imho) Part 2

Go to the Ubiquity Minimalist Documentation guidelines