Documentation: Backup for UI deficiencies?

January 14, 2010

Sue Woolley, in her article ‘Software Documentation — How much or how little?’ published in the October 2009 issue of Southern Communicator: The Australian and New Zealand Journal of Technical Communication*, stated:

Very few people these days will sit down and read a manual for a new software product. The expectation is that we can install software and start to use it straight away. The younger generation in particular is so comfortable with new technology that they dive in and expect it all to work. They explore fearlessly, and are able to master complex hardware and software concepts effortlessly.

If a user has a problem when they are using the software then they will generally either ask a colleague for help or resort to trying to find the answer in the documentation. Typically, they will “dip into” either a manual or the online help and at this point, if they can’t easily find the exact piece of information they need, they will be frustrated with the software.

Documentation is, therefore, rapidly becoming a backup for deficiencies in the user interface and user training rather than a complete solution in itself.

Do you agree with Sue? Has this always been the case or is it a new phenomena? Are humans ‘programmed’ to learn by trial and error and not ‘by the book’?

Moving out of the software arena, I know that when I’m learning a new recipe, I’ll often just start throwing things together to match what I tasted in a restaurant or at a friend’s house.

Only if it’s a complete disaster (and I want to try it again), or I figure that I might need some help do I check a recipe book or — more likely — an online recipe. Even then, I’ll often only dip into it to find the bit I need and not read the rest.

My 'Mexican' chicken -- a bit of this, a bit of that...

Of course, in the realm of cooking, I’m coming from many decades of experience, so I expect to be able to figure out most of a recipe without help. The exception is baking (cakes, muffins etc.), which require precise measurements and methods — I will check a recipe often when making these.

Does my experience with cooking and recipe books (the ‘help’ for cooks) correlate to the experience others have with software? I know that I rarely consult the help these days when installing or using software for the first time. I’ll follow the installation wizard and choose the default settings, then I’ll try to do some basic tasks once it’s installed. Assuming I have success with those (and early success to me is a CRITICAL step in convincing me that the software is ‘fit for purpose’), I may step into more advanced tasks. I may already have an expectation (perhaps based on the marketing spin on the website) that the software can do a particular task — if I can’t figure it out from the menus, the icons, the interface etc., then I’ll go hunting in the help for it — but that’s only because I expected it to do something, not because I was browsing the help just to see what’s there.

* Southern Communicator is a joint publication of the Australian Society for Technical Communication (Victoria), the Australian Society for Technical Communication (NSW), and the Technical Communicators Association of New Zealand.

[Links last checked January 2010]


  1. I couldn’t find the full article online so my comments are restricted to the excerpt above.
    Two points:
    If a user has to “read a manual” then the user assistance professional is not doing the best possible job. Context-senstive links from areas of an application to specific, concise help topics can be very effective and preclude the need to aimlessly explore, query colleagues, or become frustrated.
    Robust enterprise applications work best when users understand how the software can assist them in completing often complex business tasks and processes. Conceptual domain information is an important aspect of software user assistance and has nothing to do with documenting the UI.

  2. […] here is an intelligent blog post that discusses the assertion, that rests on a cooking […]

  3. […] Bracey of CyberText Consulting recently wrote a blog post entitled “Documentation: Backup for UI deficiencies?” In the post she quotes an article by Sue […]

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

This site uses Akismet to reduce spam. Learn how your comment data is processed.

%d bloggers like this: