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

Ah

[dragontdc.livejournal.com]

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