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

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