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

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