Previous Entry Share Next Entry
God save us from bad documentation writers
device
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...

  • 1
(Deleted comment)
Yeah, it kind of drives home that User Experience is as important a discipline for the documentation as for a product itself...

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

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

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

You're making my point for me: people like Jim demonstrate that it is possible to be a good writer in this space without also being a technical expert. It just takes work, and immersing yourself in your users' mindset, and being open to feedback and the resulting revision cycles. All of that is within the reach of more writers than seem to actually do it. :-(

  • 1
?

Log in

No account? Create an account