Wednesday, November 7, 2007

What Is Wrong with Technical Writing

What Is Wrong with Technical Writing and User Manuals?

Part 1 The Documentation Department Manager

A friend of mine was describing the Documentation Manager at his company, and a few telling adjectives and a couple of behavioral examples was enough to tweak me into scribbling a few lines about my experience with documentation managers at medium to large companies, especially the larger ones. .

There are many exceptions. There are some good Documentation Department Managers, usually men of common sense. But these are virtually non-existent any more.

Hope you don't mind my sharing my characterization of:

The Documentation Department Manager

There is no stupider, nor more obdurate, ignorant, inept, arrogant, and imperious creature on earth than the Documentation Department Manager. It is almost without exception, without prejudice but only as a realistic observation, a woman. If it's a man, he acts too petulant to be the sort of man you would hang with.

The Documentation Department Manager is paranoid, always threatened. Her criteria for excellence in her employee-subjects is abject obeisance and the same almost unfathomably misspent focus on long dashes, periods at the ends of bulleted lists, making everything look exactly the same, strict adherence to “styles” and “style sheets,” punctuality, attendance, and properly completed paperwork.

She is obsessed with paperwork and creates any number of forms to fill out, for example, so you can get a graphics person to create a picture of a keyboard. She makes checklists you have to fill out to make sure you have done all the little things she inspects and insists upon. She bullies the employees, usually passive aggressively, using the first person plural to refer to the perceived failures of the current object of her disapprobation, as in, “well, that was a nice try, but we may have to rethink our approach.”

She usually has one or two favorites, usually also women, although the favorites, like trustees, are only slightly less insecure in their positions than is the general population. The Documentation Department Manager much prefers to hire other women because men threaten them and women are more easily controlled.

The Documentation Department Manager must maintain stringent restrictions over who sees and reviews the documents; distribution is usually limited to herself and a single engineer assigned to review it for the development team, an easy restriction to enforce because very few engineers file official complaints about not having enough user manuals to mark up.

The Documentation Department Manager usually is a divorcee or widower, but if married she is usually married to an uxorious worm. She has absolutely no sense of humor, never tells jokes, doesn’t get them, and dislikes it when her employees laugh at work.

If there is any company function that involves her entire department, she will always be in attendance, restrict the agenda, and speak for her employees when someone from another department poses a question to any one of them or to them collectively. Sometimes she goes so far as to disallow the writers to contact the engineers in person, requiring them to fill out question forms and bug report forms she periodically submits to the engineers she selects.

Most of the time this creature never answers the phone unless the call is from a superior. She screens all her calls and messages, and responds when she chooses to.

She is fawningly, often nauseatingly obeisant to her superiors. She protects her phony baloney job by making sure her time sheets, status reports, and all other paperwork are filed right on time, before any other department’s (where they have actual work to do that takes precedence), and these are always accurate and contain the proper signatures, etc.

She further protects her useless position by wallpapering the halls with STC awards. The STC is of course a silly little collective of losers who have monthly meetings with topics on indexing and semicolons, a club of little exclusivity eager to deal awards like playing cards to companies willing to pay the $200 a head membership fee for their entire Documentation Departments.

The Documentation Department Manager’s constant bullying and paranoia drives out anyone with any pride or ability. If it fails to do so, she’ll get them fired. The whole department is thus typically reduced to sheepish humorless fearful little scriveners who seldom leave their cubes except for bathroom or lunch breaks (although many eat yogurt and apples out of a bag at their desks and work through lunch) and are the rest of the day huddled over their keyboards under the cold pale glow of their monitors.

The monitors, incidentally, like the computers, will typically also be of the same model, size, and type in every cubicle, as much as possible, unless the writers are allocated the used castoffs from the software coders when the latter upgrade, in which case they wind up all being the same eventually anyway. Everybody has to use the same kind of equipment, although mouse and keyboard are usually customizable, because most women use those rounded wavy keyboards that supposedly prevent that repetitive motion wrist ailment, which either afflicts or is supposed to afflict at least one or two of these brittle little victims at any one time, and you’ll usually see at least one big puffy white bandage/cast thing around someone’s wrist.

Birthday parties are all held on the 15th of the month for everyone in the department who has a birthday on that day, attendance is mandatory, the fare is cupcakes with candles in them, and one of the sheep will notice when the Documentation Department Manager’s personal coffee cup with the company logo on it is getting empty and bring her a refill, which is almost always from the pot with the orange lip indicating it is decaf.

The Documentation Department Manager’s eyes are something to study at the birthday party (which by the way is often held during months when no one has an actual birthday, and, when someone does have a birthday that month, nobody actually knows it until the Manager asks). The Documentation Department Manager’s eyes dart from face to face, noticing each employee expression, watching who is clustered talking to whom in what groups.

The Documentation Department Manager’s face is always placid and her comportment befits that of a potentate with absolute power. She dresses very professionally and knows every clich├ęd buzzword that ever annoyed a plain-speaking person. She touches base with people. She multi-tasks and revisits situations. She interfaces and networks. There has never been a problem, only issues, and there are forms for those, which are submitted periodically and “touched on” during weekly status meetings which normally consist of her reading memos from upper management which she does not permit to be disseminated directly to her employees’ e-mail distribution lists, insisting on presenting them filtered through her.

The Documentation Department Manager is the single most odious monstrosity that ever walked the earth, imposing and enforcing — with a fastidious and tireless diligence nothing short of madness — a workplace dedicated to mediocrity and misery.

One day when I have time I’ll describe the type of documentation produced by these sad little recesses buried deep within the cubed labyrinthine bowels of the Large Company, under the cold pale fluorescent bulbs. As it is, I can’t believe all this spilled out of me from the top of my head just as fast as I thought about it.