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.

[cellio]

This is good advice, yes. What I had done was to introduce the abstract idea (one sentence), then give an example application, and then speak in fairly general terms about it. I didn't think the concepts involved were too abstract for that approach, but apparently I was wrong. Now I know.

[dragontdc.livejournal.com]

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

[goljerp]

Uh... Monica is a professional. I think she was being sarcastic in her original post.

[cellio]

I am a tech writer. Specifically, I write documentation for programmers. I've been doing that for so long that writing user documentation is downright novel. I believe the draft I initially wrote was, stylistically, exactly what any programmer or other engineering type would want. Unfortunately, the users are not engineers. :-)

(It wasn't really that bad. Basically, I had led with the abstraction -- one sentence, not a treatise -- then said "for example to do blah..." (concrete example, and as it turns out, singleton implementation), and then described things using the more general terminology. I'd established the mappings, so I really thought that would be ok.

[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.

Ah

[dragontdc.livejournal.com]

Sorry. Heheh. Wouldn't you know it? Preaching to the choir again.

[cellio]

I like your idea of the user documentation being a program for users. How do you apply it in non-linear domains?

We need to explain some conceptual stuff, because our software introduces a new way of solving its class of problem, so I divided the documentation up into two major parts: the concepts and the how-to. (This is the structure they wanted.) Most people will read the former either zero or one times and the latter, probably, more than that. At least the former is there for when people dive straight into the latter and then say "hey wait, what's that?". I have liberal cross-references to make this easy. While the project that most needs this right now is delivering on paper, I am developing in pedantic HTML so that online copies are possible (including XML-based ones).

I'm not very happy with what I have, but the task has suffered from "not important, why are you thinking about that?, not important, NEED IT NOW", so I don't know if I'll be able to go back and improve it now that we have a draft. I think it would benefit from more of a tutorial approach: here, do these specific things with the software to get acquainted with it; now, let's tell you a little more about what you were just doing, and then we'll give you the complete catalogue of how to use it. Leading with a concrete example, in other words.

[siderea]

I like your idea of the user documentation being a program for users. How do you apply it in non-linear domains?

It took me a bit to figure out what you meant by "non-linear domains", and I may not have gotten it right; my first thought was "what domains are linear"?

The concise answer is "with difficulty." :) The difference in approach (and here is where the program analogy breaks down) is that it is far more important for user document to be clear than complete. This is not how any self-respecting geek would ever think a piece of writing should be. (Realizing this, btw, revolutionized my writing style in email.)

But there is a method to the user's madness. The experience of doing a thing correctly, and knowing it is correct, allows them the experiential basis to extrapolate to variations. So it is not necessary to give them all possible paths of interaction with the app., merely some representative ones. I sometimes pick a suite of paths which maps to the user roles. Jane the secretary wants to update a single word; John the administrator wants to do a batch job on a bunch of records; Jacob the sysadmin wants the data to confess. That can be the organizational basis of which paths I pick.

Sometimes the best thing is to do what you've done, and explain the conceptual stuff up front. I have found in situations where I have had to do that, it was useful to actually start with an explanation of the old way of doing things and what was wrong with it.

But even when trying to explain concepts to users, I tend to do so through examples or analogies instead of pure abstractions. I am also a big fan of bullet lists and schematics. I think your idea of leading with a concrete example is very good. There's a reason that books about SQL dbs tend to talk about bookstores a lot. Start talking about "one to many vs. many to many" and people's brains glaze over, but "Hopefully every customer will by many books and every book will be bought by many customers" clears that right up.

If you really do wind up have to explain concepts to users, be extra-special scrupulous about the documentation organization. If you're doing a top-down conceptual explanation (e.g. "This app is a flib. All flibs have three wibbits and a lep. A wibbit is...") follow it very strictly. In print you might try having a formatting protocol indicate things which are forward links, so people know "this isn't something I am supposed to know yet, it will be explained in a little bit".