God save us from bad documentation writers

[jducoeur]

I'm not going to name names, but suffice it to say I'm currently reading into a third-party package that we're integrating with. The package itself is pretty nice (and the APIs are a thing of beauty -- a compliment I rarely pay), but *man* the documentation is annoying.

It took me a while to figure out why it was bothering me so much, but I think it's the way that the docs walk you through every piddling step, to the point where something that *should* be a more or less obvious ten-second description takes a ten-page slog. Admittedly, that's sometimes necessary for end user documentation, but seriously: this is aimed at programmers and system administrators. That level of detail is just annoying for its target audience.

And it suddenly occurs to me that this feels very much like it was written by someone who doesn't really understand the system they're documenting, or the people they're writing for. I mean, yes, it's useful for you to describe the XML configuration structures in detail. It is *not* helpful to document every single line individually -- including (separately) the opening tag, contents and *closing* tag. Mostly, it looks like documentation by someone who thinks XML is a programming language, and doesn't understand it as well as the typical reader.

Basically, it feels like CYA documentation, with an emphasis on "thorough" rather than "useful". Which is annoying to me, simply because I can't hand 500 pages of documentation to our people in the field, so we're probably going to have to write the *useful* docs ourselves...

Comments

[goldsquare.livejournal.com]

I understand.

Consider this bug I wrote not long ago, for the following message: ""The file trying to be opened is a big file, and it may cause system non responsive, do you want to continue?"

The replacement, which I hasten to add has come from our technical writing department, is "The file trying to be opened is too big to open in this editor. The size limit is 20 MB."

Trying-to-be-opened. Pfaugh.

I suggested "This file is too big to edit." Perhaps that is too clear.

The pre-release draft of our User Guide is 1,526 pages of dense and relatively uninformative prose. Admitedly it is twice as big as the next smallest document - of a 20 volume set. I suggest that there is not one human alive that has read the whole thing in its current incarnation.

But I keep being told "we're moving to a wiki". As if moving dense and useless prose to a new format is a life saver.

[jducoeur]

Yeah, it kind of drives home that User Experience is as important a discipline for the documentation as for a product itself...

[gyzki.livejournal.com]

Back when I was editing Help pages at Lotus IBM, my mantra was always, "If the user is reading this, they're already confused; don't make it worse."

[cellio]

*shudder* I am saddened by how much documentation of that ilk is being produced by people who are supposed to be professionals in the field. I try to teach the writers I deal with to do better, but it's drops of water in the Atlantic...

[jducoeur]

Well, one thing I'm gradually learning more and more clearly is that it makes a *big* difference to have a technical writer who really groks the topic. You straddle the tech/writer line more than most, but there are a fair number of good "pure" writers. Jim here at Memento is a good example: he's not by any means a techie, but he spends a *lot* of his time talking to people and making sure he understands the topic pretty deeply before he writes anything down...