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.

Sunday, April 15, 2007

Introduction to the Blog of Deathware

How the Flip Durbin Microsoft Deathware Blog Began

I have been a professional technical writer for over 25 years, 18 years as a freelancer.

I document hardware and software computer products.

I am a good technical writer. I write well-organized succint manuals in which you can actually find what you need to know and can understand the descriptions and instructions. I suppose you will have to take that on faith. Most manuals belong in the Marianna Trench.

Whether it is a software product or a hardware product with supporting software, there is always software to be documented. And all that software has to run on the operating system everybody uses. And that would be:

Microsoft Windows.

Doesn't matter which one it is, which is the most recent odor, your Windows 2K/Me/NT/XP/Yadda Yadda.

For years I have grappled with, fought, struggled, endured, cursed, grappled, suffered. You probably know exactly what I mean; but you probably don't dwell on it. You just deal with it. Me too. Usually.

And then recently my computer was attacked by a computer virus, the “Spydawn” virus, aka virusburst, and, when no program available could eliminate it, I decided to begin finally to record my frustrations with this pile of horrorware.

I shall not limit myself only to Microsoft’s pukeware. Because they are merely the standard to which all crappy software must lower itself. Pretty much everything that runs on a Windows PC is evilware. Productivity genocide.

And so, recently, perhaps mostly as therapy, I began to record my experiences with Microsoft, its operating systems, its software, and all the software that we use on this silly box called a Microsoft Windows PC.

But for now, this is my first entry in what I like to call:

Flip Durbin’s Microsoft Deathware Diary and Indispensable Blog of Unlimited Application Agony

Introduction to the above:

Recently a guy sent me a link to a video file, an interview with a scientist. But to view it, I had to download RealAtlernative Player, an alternative to the system-kidnapping RealPlayer.

I watched a few minutes after downloading RealAtlernative Player. Almost unimaginably, it appears that RealAtlernative Player is more aggressively system-hijacking than Real Player, and THAT is tough to beat.

I will never, ever install anything named Real ever again, just as I shall never shop in a store that has the word “Warehouse” or “Depot” in its name.

I’ll just have to get by somehow without viewing video that requires this puddle of hyena filth.

While uninstalling RealAtlernative Player, I discovered that I had Real Player on here, and it, also, didn’t work at all. I uninstalled both. I then figured while I was at it I should install the latest Zonealarm update. That also destroyed all internet access to my e-mail, although somehow Internet Explorer seemed able to sidle through ZA’s Byzantine tangle of whoreware. So I uninstalled it and rebooted and re-installed the older version and rebooted and it immediately reminded me that there was a program update available and asked me to download it and I said no, and checked the box that let it only remind me only once a month instead of every half hour.

You know, if I had a million damn dollars, I would defenestrate this whole goddam computer, box, monitor, disks and all. I’d go to the Bahamas and be drunk all the time on frozen drinks with umbrellas in them and never, ever look at another one of these teetering little testaments to the staggering sheepish stupidity of my fellow man.

I think that what happens is that people start an application and try to do something. As they have been doing for many years. And when you type a character or click on a menu item or title bar or whatever, and the pathetic little interface cringes and fails, and a dialog box comes up that says that this or the other cannot do whatever you wanted to, well, people forget. It’s a way people have to keep as sane as they can. So they ignore everything that happens that is stupid and accept that that is just the way things are. It is what it is!

I’d like to do a psychological test. Bring in a camera into somebody’s office cube or home office, and videotape everything they do or try to do. Because when I click on something, there is 50% chance that it will explode, and a dialog box will come with an some cryptic error message such as “Error 10768 Disk Image Link Not Found” and I click OK and another dialog will come up and ask me if I want to report the bug to Microsoft. (When I click Do Not Send that dialog goes away and then another comes up and says “Unexpected Program Termination, click OK to continue.” Why does it make me click OK to continue? It is the only option. Then I click OK and the same dialog comes up again, sometimes two more times. Send Error Report? Of course I would like to contribute to the destruction of more of my time. )

But people become inured. They no longer notice how much time they spend working around the bugs. They no longer perceive the number of times something takes a ridiculous amount of time to start an application, or save a file, or any damned thing. No longer even notice how many times an action results in some ludicrous result, some inexplicable error message.

When I recently reinstalled all the applications I really needed, the default program settings were, of course, as they always are, reinstated. So I had to go ferret around in — perfect example of turdware — MS Word, the most widely used and almost surely the worst. I had to turn off almost everything, because the arrogant misanthropic dolts who designed and coded this wobbling bloated behemoth of committeeware always want to do all these things for me that they think are so cool. And who can remember where some of the most important setting options for turning off, for example, automatic paragraph format styles? If you don’t, the program self-generates hundreds of new styles every time you boldface or italicize or do anything to a word in the paragraph. (That setting is so buried it took an hour to find the bitch, and I had already found it a year ago. Just couldn’t remember. How intuitive is that?) It wants to check your grammar as you type. It wants to automatically number or bulletize your paragraph. It wants to set up “smart tags,” which are some sort of inexplicable crap. It wants to “autofill” and “autocorrect.”

Have you ever seen a new or casual user try to get rid of that bullet or number in front of the paragraph? Do you remember the first time you tried to get rid of it? Because it doesn’t really exist. You can’t click on it or select it. It just sits there until you spend the next hour rummaging around trying to make it STOP it, please STOP it. Please make it go away! It could take days to find the setting. (When I want to send an outline of the current manual, I cannot reduce the table of contents to indented text. It’s a “field.” I have to paste the fucker into Notepad, and then go back in and fix all the tabs and indents. I’ve had to do this maybe 50 or 100 times in the past 20 years. Because it would be so expedient to be able to send the TOC as a file that could be commented on with page numbers included so the reviewer would know how many pages each topic took up. But you can’t because that would be useful.)

Dostoevsky used to describe characters who are unable to ignore the constant deluge of sensory input that everyone else seems to brush off, the horrors and ugliness of physical contact with the insanities and frustrations that plague so many of our conscious moments, to the point where they can be driven to murder or suicide.

When I sit at a computer these days, I notice every minute wasted waiting for the piece of shit to do ANyTHing. And then, when it finally does it, it fucks it all up. Last week MS Word crashed horribly three times. Not only did it fuck up the file I was in, it fucked up the automatically created backup file (.WBK) and the style sheet by which both files were formatted. I save and back up files like a total paranoid, but nobody has the time to back up everything every hour or you would never get anything done, especially since everything I do requires me to wait, and wait, and wait, and then hope the heap of duct tape and safety pins doesn’t fly apart like the transmission on a ’67 Oldsmobile. (I finally resorted to saving the file with a Save As and reving the version in the filename on every save. It’s only 10,000 K per file.)

By the way, the examples I just gave you are only the most irritating. All day long every day most every keystroke, most every mouse movement, is fraught with peril, pregnant with impending doom. I just sit at the damned desk and shake my head and roll my eyes, smack my forehead, and wonder how many times today I will have to install and reboot and uninstall and reboot and reconfigure and reboot and download the latest update and reboot and install the latest update and reboot and then find out that the latest update has slaughtered my system and then I’ll have to uninstall and reboot and reinstall and reboot, each step of which process takes 10 or 20 minutes.

I was watching the Dr. Phil show yesterday afternoon (because Spike on Fridays runs some stupid Japanese stunt show instead of Start Trek spinoff reruns like Next Generation and Voyager — by the way, have you ever noticed that their fucking warp coil containment field and the holodeck are constantly broken, too, and the long range sensors and pretty much everything there is broken, too?). Dr. Phil had on victims of continual fits of uncontrollable rage. Dr. Phil explained that the source of this rage often has not as much to do with frustration with people and things as much as it is a function of the expectation that people will be rational and that things will work. But I can’t seem to shake that expectation. Moreover, I don’t think I expect too much. I just want the damned thing to do the most important and simple things. But they keep cramming more and more “features” into the clawed and clattering scorpionware instead of fixing all the crap that has been broken for a decade. It’s not just Word, it’s everything these toads touch that is poisoned. That’s why they still include the option of setting the first page of a “section,” whatever the hell that is supposed to be, to negative numbers. So I very often set the first page of a “section” to -1. That way it might print “1” for the page number. But of course it might not. Sometimes you have to make it page 0. I’m still of a divided mind as to which is more absurd, creating a page -1 or a page 0.

The lost productivity and the setbacks to user interface design progress that Microjizz has foisted upon industry must cost billions of dollars every year. And sometimes I think I am the only one left who is bugged by it.

Flip Durbin, April 9, 2007
(News, Weather, and Sports in the First 5 Sentences! See page –3.1416.)

Microsoft: Deathware Diary Entry #1 April 9, 2007

4/9/2007 8:08:47 PM

First entry in my diary of Microsoft and other software fuckups.

Today I just spent 45 minutes trying to add an entry to my Address Book, or to my Contacts, whichever it is, or isn’t, as I cannot be sure if one is a set or subset of the other. The reason I had to do this is that my system had become infected with the Spydawn virus which nothing could get rid of. Also, you cannot import an Outlook Address Book ® into MS® Outlook®. You can import almost anything else, but not one Address book of the same application into the same application. Instead, you have to find the old Address book wherever it may be and place it in the directory it will now have to be now that you have installed Outlook® into the drive/folder/directory.

I believe the correct path is:

C:\Documents and Settings\\Applications\Microsoft\Richard Nixon’s Asshole\Current Settings\Hell.

And this is supposed to be a graphical interface.

Anyway, one of the “Contacts” in “Contacts” or in “Address Book” or Contacts in Address Book or Address Book in Contacts was not there any more.

So I did a Find to find the name of the person. This was so obnoxiously ridiculously convoluted a process I gave up and sorted my Inbox – not my new Inbox, which it created for me inside Personal SomethingorAnother, but the old Inbox (I now have two Inboxes and two Outboxes and two Sent Items and I think they are all under some common heading… I could check it and find out probably in a week or so) and I found it. Then I right-clicked on it and told it to add it to my Address Book or my Contacts. One of them. Or both. Anyway, I added it. I filed it under Lastname, Firstname. Then I clicked on the New button to make a New Message™. Then I typed the first letter of the last name.

Nothing. Nada. Zero. Not there.

So I went back and realizing I was Stupid® and didn’t know how or why an Address Book or a Contact was different or the same as one another, I decided I would try to add it to Contacts and/or Address Book if I could find one that was different from the other one. I can’t remember if I did. But I clicked on Add second time and it asked me if I wanted to Update the Address Book/Contacts entry or if I wanted to add a new one. What the hell. It wasn’t there. Add, I decided. Ha, ha! I ain’t that dumb! Why would a goober even as dumb as I am want to update an Entry in a Contacts or Address Book that Wasn’t There?

Then I started up a New® Message™ and typed the first letter of the Lastname of the etnry I had just Added. It did for some reason not scroll down to the entry. So I typed the first letter of the Firstname. Not there. OK, I sez to myself, looking at my watch, realizing I had been doing this for 20 minutes, I can do this. I know I am way too stupid to understand how to use programs. So I found an e-mail message from the person in my old Inbox and I copied it. Then I tried to find Tools -> Address Book, but as anyone with half a brain knows you can’t get there from a New Message. You have to go to the Main Outlook Window. I did. I then did whatever I just said. Or did. Where was I? Right, I did a New Entry in either Address Book or you know. Then I said Save and Close. Then it said, did I want to Update or Add a New Anyway Even Though It’s Already There, Moron? I said, um, Add.

Then I started a New Message and this time I clicked on the handy To button and this brought up my, you know, Contacts or Address Book List, and I typed the first letter of the first name and nothing and then the last name of the thingy.

Not there. I just added it and it said do you want to add it anyway? Then I added it but said Update. I did this many times and then I tried to find it when making a New Message and it was not there.

Then I thought, wait a minute.

Wait a minute.

Well, not exactly a minute, more like 40 minutes and counting.

I exited the MS Outlook application and then restarted it and did a New Message and typed the first latter of one of the names in the firstname/last name and there it was.

Eight entries for the same person. All there.

My God! I am ever stupid! Ha, ha! The Joke is on me!

All of which proves that people as stupid as I am should not be allowed to purchase Microsoft® Genuine Advantage™ Software!

I wish I were a genius Just Like Bill Gates!! Then I wouldn’t have wasted 45 minutes trying to do something that should have taken 10 seconds!

I am the World’s Leading Dolt!

Flip Durbin
4/9/2007 8:34:52 PM

Friday, April 13, 2007

Microsoft: Deathware Diary Entry #2 April 13, 2007

4/13/2007 2:38:09 PM

Second entry in my diary of Microsoft and other software fuckups.

For the past four weeks I have been editing a manual. I have had to create and modify many of the paragraph and other styles. I had a style sheet attached. Every time I changed a style or added a new one, I would save the file, Turd would ask me if I wanted to update the template, I and I always said Yes.

Today I wanted to create a new file from the document template into which I had been saving all the styles.

So I go to Tools, Templates and Add-ins, and attached that style sheet that has all the new cool styles in it!

Oh, boy, this is gonna be great! All my styles are now here, instantly, no muss no fuss.

Not there. None of the new ones. Just the old pieces of shit created by the babbling bozo who worked on this document before me.

That’s OK. No prob. Maybe it only shows the styles in use. So I tell it to show all available styles.

Still not there.

I go to the Style Organizer™ and Close one file, open another, find the template, close the other file, open it up. Can’t Add and Save files into a doc file already open. OK, no problem, I copy all the stuff in the file, close the file, and plan to add the styles and to a Save As with the blank file that will have the new style sheet in it and just overwrite the previous file with the new file with the styles all added into it and then paste in the text from the file and save again. OK, no, well, a little bit of a problem now…

OK, OK, now I do the Style Organizer™ again and I open this and close that and open another, and, anyway, now I have the file open and now I choose the template file to which I had been adding all those styles for a month and I click on Add to add all its saved styles — what a time-saving feature these styles sheets are, or, or will be, when I get the styles in there, just you wait — and I go to Add the styles, make sure the fire extinguisher is handy, and then copy the styles into the document I am working on which is blank but into which I will shortly paste the text that I want.

The styles are not there.

None of the new styles or modified styles I had been creating for a month exist in the template into which I have been saving them for that month. None. Just bozo’s bullshit.

Eventually I realize I am dealing with another ridiculous MS non-feature that doesn’t work at all.

So I paste the text into a blank document and save it as Temp and then I close it all up.

I go to the manual I have been working on and open it up and then save the whole damn thing as a document template .DOT file. But of course, when I want to save it as a template file, it doesn’t show me in the Save File dialog the place where MS keeps all the template files. It shows the current directory of the .DOC file.

Fortunately, I know where they have buried all this crap. It’s in C:\Documents and Settings\\Application Data\Microsoft\Templates\Satan’s Asshole.

Anyway, I end up just saving the whole goddam document as a template and then opening it up, erase everything, paste in the text still in the Clipboard®, and save it as the filename I wanted originally, and it prompts me if I want to overwrite it and that is the first thing that has worked all day.

In other words, document templates in Word are utterly bogus. They do nothing, they store nothing. If you want the styles from another document file, open the DOC file, do a Save As to a new document with the name you want, erase everything in the file, type or paste in the new text, and do a Save again.

Tomorrow’s Lesson: Repeatedly hitting your head with a lead pipe.


From today’s on-line news, boldface italics are mine:
WASHINGTON (Reuters) - White House political adviser Karl Rove was embroiled in a new controversy over potentially missing e-mails on Friday, the latest twist in the firings of eight U.S. prosecutors last year.

The White House disclosed the Republican National Committee in early 2006 took away Rove's ability to delete e-mails sent and received through a party e-mail account. [Who could blame them?]

White House spokeswoman Dana Perino had no explanation for why the RNC, the governing arm of President George W. Bush's political party, would stop Rove from deleting e-mails. [I think we’ve figured that one out, Mr. Reuters. But read on:]

Perino said a White House review showed up to 5 million e-mails to and from as many as 1,700 executive branch employees might have been lost when the administration converted from Lotus Notes to Microsoft Outlook in 2002 and 2003.

At last we seem here to have discovered a use for a Microsoft product! National Security! If you can’t delete e-mails, just convert to a Microsoft product and presto digitalio! all those messy e-mails are wiped out! THAT’s patriotism, so congrats to Mr. Bill Gates & The Whole Microsoft Team!

Flip Durbin
April 13, 2007