People often get aggravated when they see a 400 page manual; but if it’s well indexed, they’re going to be happy that it’s comprehensive. I guess, if findability is an issue, leaving things out probably isn’t the answer.

This topic poses a dilemma for me as a user that I’m not always sure I’m answering as a writer. As a relatively experienced user of software, I only look for help if I can’t remember how to do something or if I am having a problem. It is interesting that Tom just had a revelation that answers aren’t always in the help, because that is almost always my experience in this situation!

And I HATE knowledge bases and forums, as you are recommending, Larry, because I can never find anything using them. I do a broad search and get a couple of thousand entries. Who can sort through all that? I do a narrower search and get nothing. This is why I absolutely hate the direction Microsoft has gone with its help, because I usually just want to see the help files, not all the articles and related documents on the knowledge base. If the answer is in the help files. And I have only occasionally gotten useful responses from users on a forum. I don’t think I’m trying to do anything that unusual, either.

A few random thoughts about the series:

- WordPress 3x now will offer more menu control, which should improve navigation considerably.
- one reason Google sucks for finding technical answers is that Google is a commercial enterprise and can easily be gamed.
- facets are interesting, but they are dependent on your help platform. Also they are useful mainly if the users are performing different functions.
- ebooks are an interesting hybrid medium (and one I’m working on right now). Lots of alternate navigation/browsing methods plus better use of hyperlinks.
- agree that mediawiki’s templates make it easier to organize content. But if they are autogenerated (and not watched over by a human editor), they become useless.
–thanks for reminding me that wp search results are in chronological order!
– I think your problem in the first or second part about shallow help pages is a result of a schema like DITA which tends to segment things too narrowly.
– it helps to know how your audience looks for information. A lot of It staff (my target audience) will use search before anything.
– the big problem is that people never know what to search for. All they know is how to describe their problem. I think a glossary can help with that.
- I’m a wordy/prose-oriented person. It was a shock to me when people found it hard to find information in my dense prose. Labels are important — maybe the most important thing…
–that said, for conceptual things, people like content which is a readable chapter.
–hypertextuality has a down side, especially if you need to remove a subset of the docs (for a quick start or something like that).

Alistair — I agree about the problem of documenting things which are obvious to the user. I’ve written elsewhere that screen shots are unnecessary if the GUI is well-designed and should only be used in special circumstances.

It’s actually something I’ve been struggling with for a while. I typically prefer to follow a more minimal style; ask if something is essential or not and cut any topics that aren’t 100% essential. But lately, I’ve been really questioning this. It should be as simple as, “Does a user have a question about it?” If you ever get the question, you should answer it.

People often get aggravated when they see a 400 page manual; but if it’s well indexed, they’re going to be happy that it’s comprehensive. I guess, if findability is an issue, leaving things out probably isn’t the answer.

Anyway, thanks for the post. Definitely digging it.

-Dan

Totally agree and this is how one of the groups I worked with recently approached in-house application development, and how I’ve been setting up open-source CMS’ too. This is that ‘point-of-need-learning’ or information need I think I may have mentioned previously.

I also don’t consider it embarrassing at all to ask for it this way and not have to poke around in a help file. Today’s knowledge workers are busy as ever, tasked with being as productive as possible (it’s a global market place now folks; more competition). Having to run a series of tasks and actions just to get that little bit of information is wasted effort and inefficient; unable to effect or achieve the desired result with reasonable economy of means.

For example, here’s one I got this morning: ARERR [8703] Bad attachment size

What that really means is, you can’t attach anything larger than 2 MBs. And you can only attach certain kinds of files. I’d like to be told that here because (embarassing as this is to admit), I really don’t want to go poke around in the help file. Just tell me what’s up so I can keep going, please.

As Steven above pointed out in his entry on finding info on using accents in Word, how many times does a user get stuck at the start simply trying to figure out, “What’s my problem called??”

If writers in a department are supporting multiple complex projects, the best way to get everything “done” can be to do the bare minimum of getting a change documented, without ever improving the contextual information about how the features interact with each other.

If a company has many products, clients, configurations, user types, etc., it’s a large task to keep straight who needs what information. But perhaps some of those user types are just not going to use the help system. They’re going to call their IT people, or their questions are rare and specific enough that they will use a knowledge base or user list. Or, conversely, maybe they are the only people who will use help, and so we should scrap the basic tasks and go right to the complex topics.

It can be tough to justify stopping the merry-go-round of deliverables in order to survey the passengers, per se, but at least after that, one could stop writing for those who aren’t riding.

When I use a help system, I don’t expect all the answers to be there. I know I might have to venture to the forums or call support. I do, however, expect to be able to quickly determine whether the information in the help system or not. With a wide, shallow help system that has good labeling, I can do that. I can open one or two books and be satisfied that I’m finished looking.

That’s less likely to happen to me, though, if the writers are well versed in what users like me are looking for. It’s time-consuming to gather that information, but it saves effort and money in the long run.