ITauthor

Rhonda Bracey of CyberText Consulting recently wrote a blog post entitled “Documentation: Backup for UI deficiencies?” In the post she quotes an article by Sue Woolley:

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.

Rhonda asks “Are humans ‘programmed’ to learn by trial and error and not ‘by the book’?” I think she’s onto something. I suspect that over millions of years of evolution a genetically programmed impulse to play around with things as a way of figuring things out has served the human species extraordinarily well. And so today, if given some software (or hardware), plus a set of instructions telling you how to use it, most of us will ignore the instructions and just try to start using the product.

For example, yesterday, for the first time, I was using the PushOK SVN plugin for Madcap Flare to work on our main online help project. My colleague Graham and I were both working on the same project at the same time. He’s been using the plugin for a while and I was on the phone to him asking him questions and we were working things out, in the style of: “Okay, now I’m going to click on such and such … now see if you can … did that work for you … did you get my changes?” And pretty soon I’d figured out how to do the basic stuff: check out, update, commit. Part of the thing that demanded some trial and error on our part was that the source control menu text within Flare uses Microsoft Visual Source Safe terminology rather than the standard CVS/SVN terminology we’re used to (for example, “check out” means something different).

At one point in proceedings, as we were batting things back and forwards figuring out how it worked, I joked to Graham: “You know what we really should do? We’re technical writers - we really should be looking in the help system!”

Like most people (and I quite often bore people by asking them if/when/how they consult the documentation for the software they use, so I’m pretty sure I’m part of a majority in this respect) I only consult the help system:

• If there’s no local expert around to ask
• If I’m in a situation where I don’t want to ask the local expert because I don’t want to let on I don’t know whatever it is that I don’t know
• If I can’t find the information via Google, or I happen to know the help system will do the business for me (for example, I know I can easily find details of FrameMaker keyboard shortcuts in the application’s online help, but, in contrast, I know there’s little point looking in the online help for Microsoft Word because the search facility brings back so many inappropriate results it’s far quicker just Googling for the information)

And what about printed documentation? (It’s funny, when I talk about “documentation” a lot of people still immediately think of printed books, when in fact the work we produce only rarely ends up being printed. This is probably one of the reasons some folks prefer to talk about “user assistance” – but I find that term confuses most non-IT-professionals.) Well, let’s think … when do I read the paper manual for a software application … emm … never? Since I got broadband access to the internet (back in 2003 I think), I can’t remember ever having consulted a paper manual as a way of finding out how to do something in a software application. And I used to spend a small fortune on computer books. Before my access to the internet was “always on” my home office was cluttered with stacks of computer books and binders full of printouts. In the last few years all of that stuff sat untouched, gathering dust, and it was only towards the end of last year that I finally got round to chucking it out.

But back to Sue Wooley’s article:

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

If you document software applications then you’ve almost certainly had the experience of having to document something when you know you’re writing a whole screed of instructions to compensate for a poor piece of user interface – and it’s obvious that simply moving things around the interface would make this bit of documentation redundant. That’s when documentation can be a bit soul-destroying. You of course petition the developers, log a bug or submit a change request, but in the meantime you have to document what’s there, in the full knowledge that you shouldn’t have to be writing this and the best outcome (for the end user) would result in the deletion of your work.

However, we have to be pragmatic about such things. Sometimes user interface design is just left up to some poor developer who, while he/she may be fantastically clever and a brilliant coder, has no real understanding of usability. And once a bit of poor user interface design slips out into a release it can be very difficult to repair because, unless they’re backed up by complaints from customers, requests for changes to the user interface generally get assigned a low priority. This can be very frustrating, if you’re the one who raised the issue, because some of these things can cause a lot of damage to usability but could be fixed by a little, two-minute change in Visual Studio. The hidden reality, though, is that even a quick two-minute change in Visual Studio can sap QA time by requiring changes to test scripts, updates to automated tests, manual regression testing, and so on. So a two-minute user interface change, that might prevent several hours of work by a technical writer, is often destined never to happen because of the QA cost and the feeling that any additional change carries a risk: so if it ain’t really broke, don’t fix it.

I don’t believe documentation should ever be thought of as “a complete solution in itself” (it should be an integral part of a product), but neither is it always “a backup for deficiencies in the user interface”. The products I work on are usually large, complex systems, where there’s simply too much in there to show it all on one page or in one window ­– with everything achievable within two or three clicks. Some of it just has to be tucked away somewhere to allow other things to be more accessible. As a result, you need some way of helping people find the rarely used pieces of functionality. Unfortunately you just can’t always make complex things simple within an application. Some things need explained. And as for training, well, you can develop and deliver a great training course, but what happens when someone completes a four-day course, covering lots of detail, but then doesn’t need to use a particular bit of the application until six months later?

There are good reasons why documentation is necessary. But, having said that, I’d still maintain that, in reality, for most of us, documentation is the form of assistance that you go to as a last resort, when there’s no other option.

But don’t get down-hearted. If you can create a help system that’s well targeted to provide people with the information they’re realistically going to be looking for, if you can structure it in such a way that people can find the information they need quickly without having to trawl through a list of 20 unordered search hits, if you can write concise and easy-to-read topics that explain just that nugget of information the reader needed to know … then your work is not in vain. Somewhere, some time, you’re going to help someone out. You’ll have avoided some aggravation. You’ll have reduced that day’s global curse count.

And sometimes, no matter how great the help system is, people will choose to ask a human being for help. Why? Well, because we’re social creatures and we’re often just looking for excuses for social interaction. Asking for help with the new IT system (or maybe just bitching about it generally for a while: I mean, the old system worked just fine – now I can’t get anything done!) is a chance to interact with someone, get to know the person at the next desk, chat to the girl in the next booth, make friends or maybe just kill some time.

And anyway, what’s so bad about providing a last resort? Isn’t it good to know we’ve provide people with something they can turn to when all else fails?