For a long time, I was a technical writer. My first gig was with an accounting software company. Whenever you purchase a piece of software, you expect a user manual of some kind, whether on the web, on CD, or a printed version. They had no documentation to speak of, so that’s were I came in.

To write documentation for a product like a mid-range accounting solution, you need to understand how the product works. So I dove in, played with the program for months. Furthermore, I also worked the help-desk, so I got to know the commonly asked questions first-hand. I think I was pretty good at what I did, because once I created some printed manuals, the calls came fewer and further between. If new questions came up with increasing frequency, I addressed them in my next revision of the documentation.

My next job involved writing documentation for a college. It ranged from rearranging Microsoft documentation (since people found it too “cumbersome”) to documenting how to get usernames and passwords.

If you are a writer, you will run into an editor at some point. Whether you write for a newspaper, are a novelist, or a corporate website, you will run into an editor. If you are lucky, you and said editor will see eye to eye. If you are not, you will run into a very common occurrence, an editor with an agenda. Now, the word “agenda” sound ominous, but should not be taken as such. It just is what it is, a preconceived notion of how things should be and an unwillingness to listen to another point of view.

Example: Your editor may be married to a certain word, phrase, or style that may not make sense to your audience. The editor may like a certain phrase because he is comfortable with it. The phrase “focus-free button” does not mean anything to anyone but a programmer. Though a common user may encounter focus-free buttons everyday, the use of the term may confuse the user, in which case, they may find the documentation “cumbersome”.

Sadly, because said editor has the higher position, his word goes. Sometimes, there is no real explanation for the desire to make changes. Personally, I think that some editors just make changes to feel like they have their own personal stamp on the documentation. Maybe it’s just a way to exercise power. Hell, I had one editor make me re-write all my documentation in second person, “just cause”.

Maybe this is why blogs are so popular, a writer’s undiluted thoughts, well at least any filtering is usually their own.

I’m not trying to downplay the importance of editors. A good editor will point out mistakes that you miss (not just incorrect spelling, but style problems), and will also try to enhance your good tendencies. However, some editors forget that they are not only reading the draft in the role of editor, but also in the role of target audience (or purchaser).

Technical writing and its associated editing takes on a pretty weird little role. In my experience, the editor is someone on the technical side, someone used to the jargon common to creators of software or architects of network systems. The intended audience, on the other hand, usually the exact opposite. They are uncomfortable and intimidated by the terminology. In many cases, it can further heighten their insecurity about not being able to function without the documentation (after all, we’re always told how easy everything is on a computer).

So, if on one hand there is an editor with a personal agenda and on the other a nervous reader… Well, you get the picture. Add to this the fact that documentation gets the same amount of attention that junk mail gets, a glance, and disaster ensues.