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

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