![[personal profile]](https://www.dreamwidth.org/img/silk/identity/user.png){kind=small}
Jan. 24th, 2012
Somebody at Ars Technica got really punchy this week. This article is a fine piece of dry silliness, although it kind of takes you out into a dark alley and beats you over the head with the metaphor until you cry uncle.
(To be fair, Microsoft does seem to have opened the door for this with its own bit of inspired ridiculousness, which appears to be frighteningly real...)
(To be fair, Microsoft does seem to have opened the door for this with its own bit of inspired ridiculousness, which appears to be frighteningly real...)
Somebody at Ars Technica got really punchy this week. This article is a fine piece of dry silliness, although it kind of takes you out into a dark alley and beats you over the head with the metaphor until you cry uncle.
(To be fair, Microsoft does seem to have opened the door for this with its own bit of inspired ridiculousness, which appears to be frighteningly real...)
(To be fair, Microsoft does seem to have opened the door for this with its own bit of inspired ridiculousness, which appears to be frighteningly real...)
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...
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...
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...
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...