Add Yours
  1. 1

    Probably the real point is: users hate to read bad instructional or help texts, since they’ve read so many crappy ones. A good writer can create helpful and accurate documentation that’s also brief and quick to read. Documentation isn’t yet really part of the usability process that most companies follow–it’s still tacked on at the end in place of real usability testing, or else is written without ever putting it in front of a real reader to see how he or she responds to it.

    At AMD, I had to write about 200 pages of documentation for the most complex CMS I’ve ever seen: it literally reduced some people to tears to use it. (No, they’d never bothered to do any usability testing or even write a spec…) I was told over and over just to “write clear documentation and it will be fine”, although I was discouraged from actually showing my drafts to anyone. I ended up doing that anyway, of course. But the attitude that documentation isn’t really part of the system or project is amazingly pervasive, as is the attitude that documentation can salvage bad design or programming.

    Another point to remember is that designers tend to make bad writers, as do programmers, biz folks, and many IAs. Really, many people make bad writers, since it’s a skill you have to cultivate constantly. There’s really no substitute for having a good copywriter /editor on any project.

  2. 2
    Jared Spool

    It’s interesting that this is the topic of my speech today at the Winwriters Conference, an annual gathering of technical writers.

    My session talks about the role of technical writers in web design, based (of course) on our research on where users need verbal assistance when using the web.

    One interesting finding that I’ll be sharing is a correlation we discovered last year on e-commerce sites: When users click on a link labeled “help”, they are four times less likely to purchase than if they didn’t click on the link.

    Now, of course, this is a correlation, not a causation statement. Our thinking is that, in an e-commerce situation, if the user needs a generic help function, they are already way too confused and the odds of help rescuing them is extremely slim.

    So, it tells us that the sites where users didn’t need help are the ones that actually provided the best assistance. This only comes from quality design, which includes verbal design — the domain of a good writer.

    My $0.02, anyways.

  3. 3

    From what I’ve seen, help is the course of last resort– most of the users I’ve tested with do not want to click that button, because they think it will not help them. In fact, they mostly think it will be a big time sink.

    I really think the answer is inline help, as much as possible, and little “what’s this” “learn more” and question marks/info links that lead to contextual help. the big main help should always be there, but as the mother ship holding all information that users can dock into from any spot.

    As for writing, i am amazed at how many projects don’t use a writer. amazed, since when we test (again, i know) a good number of the problems we see are writing problems — labels and instructions.

    Of course the downside is project with a writer often have the same problems, because a copywriter is not necessarily a label specialist.

  4. 4

    I tend to write help and user docs (like tutorials) toward the end of the beta rollout, when we first present a new application to users. Then I find out what parts of the documentation are lacking and go beef them up. User-testing for documentation, if you will.

    My rule of thumb is “short enough to scan and understand, long enough to prevent most phone calls.” The tutorial for our teachers’ little CMS (for posting homework, class news, and the like) is 25 pages long with lots and lots of screenshots. Short enough to read in an evening at home (the PDF is about 900k, easy to download or throw on a floppy). The supplemental help docs scattered throughout the application probably amount to another 2 pages in paragraph-long chunks.

    Of course, no amount of documentation can help a badly designed application.

  5. 5
    Ron Pinder

    Ah, technical documentation, sadly, the bastard child of technology. Sounds harsh? Perhaps. But as I come from a tech writing background that’s been my experience.

    There’s this tacit understanding that technology requires user documentation. This exits in vendors and customers alike.

    But this near axiom isn’t necessarily true. Many good web sites out there have no help of any kind. My hunch is there’s strong inverse correlation between the number of features & size of documentation with the vendors real understanding of the customers business and users work. (see G. Colony’s article “Naked Technology”, Forrester 2002)

    Ah, yes but what about very complex systems? I once witnessed a unique approach to product development at a large network equipment vendor. They had the project from hell with the customer from the same place – network wide s/w upgrades. The existing product had a 400+ page “follow this or warranty is null and void” class documentation.

    So the project team gave up the ouja board science approach to customer requirements practiced in most vendors conference rooms. They established an in-depth understanding of the customer’s process and generated focused technology independent requirements. One of these was no documentation. None. Zero. Not one page. (No, they didn’t just put it on-line).

    They did it. Not sure who was most amazed, the vendor or the customer.

    Perhaps what we need is not minimalist documentation but minimalist applications. The Swiss army knife approach to features and customer value serves what is termed as perceived customer value. Not the same as true customer value.

Comments are closed.