Looking for writing-related posts? Check out my new writing blog, www.larrykollar.com!

Friday, July 07, 2006

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.


  1. I've always been of the opinion that a good boss lets you know what they want, but doesn't stand over your shoulder while you're doing it.

    I worked in offices for many years and I always saw the different types.

    The Best - The important thing was getting the job done and they worked with you to do it.

    The Needy - They could never get thier part of the job done and you constantly had to stop to help them.

    The Backstabbers - They would work with you, but any minute thing they could find, they would trumpet how bad your work was and how much better their work was.

    I've also been in the situation where I was left out of the loop and then expected to know everything going on. Most disconcerting.

    Hope things get better for you.

  2. The latter situation is the one I'm usually in. The boss I have now just get tossed into this department, so I was really trying not to get on his feet while he was trying to do the same... didn't work out. It doesn't help that he's out on vacation, I think he'll be back next week.

    Maybe he can help fix this situation when he gets back. Maybe.


Comments are welcome, and they don't have to be complimentary. I delete spam on sight, but that's pretty much it for moderation. Long off-topic rants or unconstructive flamage are also candidates for deletion but I haven’t seen any of that so far.

I have comment moderation on for posts over a week old, but that’s so I’ll see them.

Include your Twitter handle if you want a shout-out.


Related Posts Plugin for WordPress, Blogger...