Programmers. Argh (2.0)

Seagull: someone who makes a lot of noise, craps all over everything, then flies away.

It’s been a while since the last one of these, before I started Tales from FAR Manor in fact.

One of my recurring work projects is a four-volume set of software firmware documentation — one volume each for features, provisioning (i.e. installation and configuration), management, and troubleshooting. These are the “wonk” documents, as opposed to the consumer documents. I depend pretty heavily on the developers (i.e. programmers) to get me the information that I need to put into these documents, and their usual modus operandi is to wait until the last minute and drop a ton of changes on me.

On occasion, some of the things they want just, as Mrs. Fetched says, “get all over me.” In Programmers. Argh. 1.0, it was a request to add text to the manual, verbatim, that contained a howling grammatical error. This one is a bit more complicated, and started a couple of months ago with this request:

We *really* need section numbers in the documentation. I am asked *all the time* to explain how certain features work. I would like to just reference the correct guide and section number for the answer. With the way the document is structured, I have to go into the document and find a *string* to reference that can be searched on to find the information.

Now you have to remember that this is a programmer manager asking for section numbers. I haven’t used section numbers in customer documentation in nearly 20 years, and 98% of what I’ve done was for technically-oriented audiences. Not to mention that section numbers really wouldn’t solve his problem: the manual needs a better index, and he can use page numbers to refer them to the right place. I need to do a better job of indexing, I’ll be the first to admit, but the thing that bothers me is that they didn’t even think to include me in the discussion, or even forward any kind of post-mortem to me. I like getting comments about my work, so I can make it better (and if you, yes you, are wondering whether I want comments on my blog, the answer is yes).

Now it was my turn to make a mistake: I quickly wrote a response, saying pretty much what I just wrote, and Notes (once again) came up b0rk3n. I saved the reply in my Drafts folder and promptly forgot about it until it came up again.

Fast-forward to last week. Here come the comments, courtesy of the guy who pulled 1.0 on me, and guess what was at the top of the list? I started looking for the original request and found the response in Drafts. Cursing Notes and the IT department that forces us to use it, I updated the reply and sent it off. The bit-munchers were copying everything to my new boss, which only irked me more — not only do I suspect them of deliberately waiting to drop all their comments at the last minute so I’ll be the one late and officially holding up the release (giving them more time to fix their problems), they are trying to make me look bad to my boss. I sent him the general history of the project, including the stuff that has gone on before, and suggested he contact previous managers for confirmation.

He dug in, I dug in. You can’t out-flame a writer, and he probably knew that: all he had to do was stonewall until it was time for him to leave on two weeks vacation. But he may come back to find the company short one tech writer. One of my co-workers helped to diffuse the situation somewhat, arranging (and refereeing) a meeting between me and this guy’s manager (who kicked off this particular request). We compromised: I agreed to put chapter numbers and titles in the headers, especially since I’d planned to do it in the first place, and he agreed to start copying me on customer squawks that involved documentation. But I’m still pretty cheesed about the whole thing.

Time to find my resume and start emailing, I guess.