a lesson in user documentation

[cellio]

I wrote some user documentation for a feature. The concept is general, but there is only one concrete case within the UI now (and for the forseeable future). Being an abstract-thinking, API-focused, programemr kind of person, I wrote an abstract description using a concrete example. That's what everyone would do, right? You don't want to limit the future usability of the document, after all -- generality is good.

This will, apparently, confuse the users. Everyone knows you can only do X to a Y, so a discussion of doing X to Y, not X to {group including Y}, is needed. I am assured that this is true.

I can't trade in our users on different ones, so I guess I should simplify the document. If they add a second case of this next quarter, though, I reserve the right to mock someone. :-)

Comments

[geekosaur]

Some users are permanently confused. (I have to deal with a few of CMU ECE's.) On the other hand, it's not clear to me that a better example would help them. :)

On the flip side: you mentioned that there's only one case "for the forseeable future", and some of us take a general example as a hint that there are in fact multiple cases....

[anukul.livejournal.com]

Edward Tufte offers the maxim of "PGP"; particular -> general -> particular. Introduce the concept with a specific example, connect it with the general principle, and then reinforce it with another specific instance. Leading with an abstract concept can definitely lose people. Most folks don't want the extra overhead of a general tool; they just want to solve their problem. Even if we believe that learning the generalized concept will pay for itself in the long term, that decision should be left to the reader; not presumed by us.

In as much as it is fair to generalize about teaching, I believe it is good advice.

[dragontdc.livejournal.com]

You need a professional. Hire a tech writer. (Says the career tech writer.)

[siderea]

No, user documentation really is different. :) Since I usually am writing things which will have both end-users and developers coping with it, I usually write two pieces of documentation.

I like the Tufte comment above. The way I think of is is that the developer needs to understand the application so for her, the documentation needs to be descriptive. The user needs to operate the application, so for him the documentaiton needs to be prescriptive.

My developer documentation is very much like the sort of essays you've seen me write in other forums. It usually starts with a declaration of the point of whatever it is I've built, and then a conceptual overview of its organizing principles or abstraction model or whatever I think is most core to building a comprehension of how it all works. That's the last thing a user needs to know. They don't want to have to understand something big to do something small.

While I have been known to wedge the "this is the one thing you need to understand" short-essay-answer into my user documentation, generally my user documentation is completely task/workflow oriented. It may start with a declaration of who should use the app, and under what circumstances. "This will delete all your data. If you are not a sysadmin, you should probably not be touching this button." Then I launch into a description of how to do various things with it, and generally my over-all organization is based on the organic workflow a real user might typically follow. e.g. I don't explain how to delete something until I've explained how to create it.

A very useful paradigm is to think of user documentation as a program for users. That is, it is the the program with you are loading into users that the users will then step down through, to interoperate with your app.

With humans, you generally have to presume single-pass compiling or even, gods help you, on-the-fly interpretation. So you have to declare variables before using them, you have to define routines before calling them. This is exactly backwards from the top-down inclination of the usual coder, who wants to start with Main.