Justin du Coeur (jducoeur) wrote,
Justin du Coeur

God save us from bad documentation writers

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...
Tags: programming

  • Post a new comment


    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

    Your IP address will be recorded