At best, a manual can be oriented to predefined tasks and known problems, at worst it is a dense technical read with a broad overview intertwined with nitty-gritty details.  Neither approach considers how people actually work with documentation.  Firstly users never consult a manual unless they encounter a problem they cannot solve on their own.  And even if they do consult some form of help reference,

“[Users] encounter a usability problem on average about once every 75 minutes and typically spend about a minute looking for a solution” -When and How People Seek Help with Computer Applications

I call this the 1st rule  of triage support: a problem or question not resolved within 60 seconds won’t be resolved (unless the problem is really bad).  This law explains why Twitter and Get Satisfaction are so successful: users find the most up-to-date answer upfront instead of  guessing their desired solution might be in some help menu or digging through forum posts.

Documentation and help resources must be thought of in holistic terms, as a part of the user experience spectrum instead of a disparate collection of tools.  To push us closer to that less abstracted understanding we can change the definition to user support. Abandoning the terminology of help and documentation and thinking in terms of user experience and support includes more than just manuals and forums.  This changes the strategic importance of different items, magnifying some things and reducing others.

Don’t think of Documentation

As best psychologists can tell, humans recognize and categorize things in two ways, as described by instance theory and abstraction theory.  Instance theory is that we store a central prototype for a category, with all sub-items being variations upon that prototype; an instance of it.^*  I believe we generally think of documentation via the instance method because documentation also has a literal meaning of recording details and specifications, as in “The case was very well documented” and due to way developers implement documentation resources.

Documentation’s central prototype is a manual, of which there are many variations; wikis, FAQ, knowledge bases, etc.  Thinking in this manner will bring up related help prototypes (through spreading activation) such as a mailing list and it’s variations, such as a forum.  Such thinking prevents us from improving upon the satus-quo, it starts our thought process at a solution and walks backwards into the problem.

Abstraction theory holds that we string together different categories via shared characteristics. What do manuals, wiki’s, FAQ, knowledge bases, mailing lists, forums, GetSatisfaction, IRC, and web-chat all have in common?  What is “documentation” in the context of the user experience?

All of these things are just forms of user support.  I want to talk and think about user support as a collection of actions, products, and features compensating for when the user interface falls short of perfection.  This starts thinking at the problem and designs solutions for it.  Solutions I call support structures.

This seemingly small tweak in definition leads to big changes in reasoning.

Support Structures

The knowledge base/wiki

If a user fails to find relevant results on their first search, 50% will not search again^**

Yet most online documentation only offers links or a search box at the end of the page.  Sadly, the user is more likely to work around the problem or drop use of a feature -like Taskfox,

For these work-around episodes, the mean task time was 20 minutes and the median task time was 10 minutes. We estimate that use of available functions, had the participants known of them, would have reduced task times by 75 percent. -When and How People Seek Help with Computer Applications

So why not try to engage the user by offering a GSFN submission or chat support at the bottom of every page?

The Herd

The herd delivers information about a command, will show up high in google searches for the command, and will get a lot more traffic than any knowledge base we erect.  So why not make examples editable and sync them with the knowledge base?

Click to enlarge

This is extremely evolutionary, re-purposing material in pre-existing support structures.  It’s not a technological leap but a cognitive one.  Just as Ubiquity is only a cognitive leap- using a very old interface in places where it’s best suited for a task.

Error Pages

A seducible moment is when a user’s goal changes from performing their primary task to fixing the whatever is preventing them from accomplishing their primary task.

Google found that by placing the spell correction feature not only at the top, but also at the bottom of a search they were able to double it’s usage.  Users skimmed over what could have helped them originally because it was at the top.

Error pages could exploit this by offering a “best effort” landing page along with re-purposed knowledge-base materials.

Guided Exploration

Only a fraction of users have add-ons  due to the high barrier of actually adding them.  If we don’t just automatically add top-tier 3rd party commands we could at least offer them up on error pages.

However, we are limiting ourselves.  Google has replaced bookmarks, Wolfram is attempting to solve problems, and Bing wants to answer questions.  Isn’t Ubiquity not only a shortcut for these functions but also a replacement?  Why not embed suggestions where it is relevant, be it landing pages, a custom search page, or within the website itself?  Normal Google searches through Ubiquity could be redirected to a customized Google Custom Search page re-skinned with some JS magic:

Click to enlarge

This might seem hokey, and it’s effectiveness would be very limited in getting new commands onto Ubiquity.  But think of how the click-through rates and keywords from this “feature” can be used to improve the parsers logic.  User support isn’t just about teaching users, it’s a part of the user experience, it’s part of the testing cycle which improves Ubiquity.

Developer Support Structures

A more complex interface (such as MediaWiki, Trac, and Merc) filters out users who probably shouldn’t be patching code, logging bugs, or writing developer documentation.

However, the core developers are overworked trying to get the parser working,  internationalize it, integrate Taskfox, architect Jet Pack, design the UI, and help out on other Mozilla projects.  As a result, the core commands (among other things) have gone stale.  Commands are simple enough that even transient volunteers could improve them immensely.

I think a modified rule for these smaller items could be “Contributing shouldn’t take more than 60 seconds.”  Quality code takes longer than a minute- but hasn’t everyone found themselves spending hours on Wikipedia when they meant to just fix a minor thing?  Even hosting the commands on as individual GitHub projects would go long way towards increasing their exposure.

* Anderson, John. Cognitive Psychology and its Implications. New York: Worth Publishers, 2004.

** 47% of the users who failed only tried the search engine a single time. Another 30% tried twice. Less than 25% tried more than twice to get the search engine to produce a successful result…

Now, the designers of many of the sites we tested went to great lengths to get users to continue searching. They put in encouraging search tips that said “Try a new search using different terms.”

However, we did not see any evidence that these tips encouraged any user to search again. They pretty much assumed that the first (maybe second) try was the best they were going to get…

These results indicate that designers get one, possibly two chances to help users find their content with Search. If most of the users don’t find what they want in the first try, it doesn’t seem likely they will ever find it.

-People Search Once, Maybe Twice

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

You can check out the embedded video clips and other media related to the study here. Perhaps I will get the paper into a student research publication, it’s on my summer to-do list.

I don’t really need to make it perfect for my closed tests.  If I were doing this for a real ad I would have a single, flowing sequence like search on Craigslist, check prices on Ebay, email it to a friend, and  insert a map.  I am working out some compression issues so I can put the iMovie project online to make remixing easier if you are interested.  Suggestions are welcomed in the interim : )

There is a lot of talk about community building for the Ub command developers. My main concern is UI engineering; how can we help command developers create Humane commands? Earlier I blogged about the translate command, offering some suggestions, hoping it would help future command developers. Sadly, we can’t expect trained Usability professionals to review every 3rd party command.

One of the things that I find interesting is how Apple has evolved their 3rd party developer ecosystem. While John Gruber has railed against the inconsistency of click-through in the Human Interface Guidelines for OS X, I doubt users ever notice a difference, nor cause usability issues.

While Apple’s Human Interface Guidelines are good, it’s Apple’s Interface Builder that is the driving force behind the high quality 3rd party interfaces OS X users enjoy. Not to say HIG’s don’t have their place- they help us define and create countermeasures to problems. But auto-spacing/alignment, excellent 1st party UI’s, and good design patterns are demonstratively more effective at helping developers than a list of guidelines and ratios for the distance between buttons.

It is this spirit of providing solutions and value to developers that I hope the Ubiquity community embraces.

I have been running into two types of usability problems in my testing of Firefox Ubiquity. One set of problems is with Ubiquity itself, it’s discover-ability, the display of suggestions, help, etc. The other set of problems is with the commands.

The Translator command caused a lot of confusion. It would change the contents of a page, and users didn’t know how to revert it.

So instead, I thought up a translator lens that allowed us to visually communicate how to revert the page and provide control after the command has been executed. That might be a bad idea, more than 1 way of doing things…

Below are some mockups. They are public domain and both link to my Flickr account. Get the Photoshop files here: UbiquityTranslatorPSMockup.zip.

In addition to the overall problems, some testers expected translate to translate the entire page if they didn’t have a selection. I’m worried about modality on this one (since they might not realize that they have a selection) but we can handle that later.