Technical writing: Writers vs. Editors


Here's a little background on me. I've been writing articles and technical documentation for over 20 years, which is just less than half my life. I started writing articles and type-in listings in BASIC for computer magazines as a way to pay my way through university, and as it turns out, I was quite prolific.


I remember one month walking into a newsagents (I'm not quite sure what the American equivalent of a newsagents is, but perhaps imagine a 7-11 that includes the magazine racks from a Borders) and counting at least a dozen different magazines containing one or more articles I had written. In other words, I've written a lot. (And I've written some books too, which sold very badly, but there is no need to dwell on that.)


Now, I'm not a particular great writer. I didn't study English at university, my degrees are in computer science and electronic engineering. I just have a passion for writing, and for explaining things as best I can. And if you have passion, that can get you far. It can even let you get away with starting sentences with "And" from time to time.


This week I've been thinking of that eternal struggle between Writers and Editors. This came about because in my current position, I'm acting as both a writer and an editor, even though officially I'm neither. On one hand, I write some whitepapers and technical documents in my free time. On the other hand, I have the task of performing the final check on our team's documentation to make sure it doesn't contain any words or references that might get us (that is, Microsoft) in legal bother. I use a tool that scans the docs for all sorts of politically incorrect words, and produces a list of warnings. It's very entertaining to read this list from time to time. I don't know half the words in it.


Anyway, this week I got edited. I'd just written a document, it had been edited, and I was asked to review the results. Have you ever used the Track Changes option in Word? Every time someone makes a change, the original is crossed out in a different colour with a load of squiggle and lines in the margin. My document did not have one single, solitary line that did not contain a word or phrase that wasn't crossed out.


Now, like I said, I'm not a great writer, but this just made me sad. A lot of the changes were completely unnecessary. There were phrases that were re-worded just to suit the style of the editor. Any indication that this was something I was written had been totally expunged. Like a good piece of technical writing, it would be impossible to compare it to another document and deduce who wrote it. It made me sad because I didn't think this was entirely necessary in this instance. The document did have my name on it, and yet it bore no resemblance to the document I wrote. It was now a piece of work that was created by an Editor.


I've been working here long enough to know that arguing with an Editor isn't going to get you anywhere. They do have rules of the English Language (or in this case, the American Language) on their side, and you are always going to lose. In fact, this is often a very good thing. When writing pure reference material you must be consistent and accurate and refrain from colloquialisms (which localize very badly as you might expect) and a more conversational writing style. Reference material written by Writer A must look like reference material written by Writer B. That's not to say there aren't good technical writers and bad (there certainly are) but the key is that the work must be consistent.


This means that writing reference material can be quite soul-destroying. Sometimes it can seem like imagination is to be left at the door, and any enjoyment you might get from writing is voided. Of course, that's a purely negative view because as it turns out, imagination is a huge requirement. The ability to plan the documentation, see it in your mind as you work through an explanation, put yourself in the place of the developer reading it - all these are very important aspects of working in a technical writing team.


Still, having your personality expunged from your work is also depressing at times.


But a few days later, suddenly I'm the one that is the bad guy. After checking our team documentation, I found some words and phrases that trigger that political incorrectness filter, and I am the one to ask the writers to make the changes. Here's an example: we don't use the words "foo" and "bar" here at Microsoft. As programmers, you and I know those words well. If we make up a sample that includes "foo" in the name, we know that we can replace that part with our own name. It's an unwritten rule in technical documentation.


Unfortunately, it's a written rule in this team that we don't use "foo". I'm guessing that is partly because of the root of that word, and partly because of localization issues, and partly because the person who put it in the list wasn't a programmer but was an English Major and didn't like it or know the special meaning it has attained. Which is a shame, as I think that it's good to speak to developers in a language that developers understand, but hey, I don't get to make the rules here.


So as part of my job this week, I've been asking writers to change stuff like that, and of course some push back and ask why and quote sections from Encarta that prove the word they are using is a real word, and any of the politically incorrect homonyms are purely in my mind. But sorry guys, they aren't going into the docs, and thems is the rules. I hope this doesn't discourage the writers from doing their job, because I know exactly what it feels like.


I'm sure any technical writers reading this far already do this, but I would love to encourage all technical writers to write outside work. Write a blog. Write a novel. Write long emails to girlfriends/boyfriends/relatives. Just write, and get to use your real voice from time to time. It helps a lot when you have to go back to documenting an API on Monday morning.


As you might be able to tell, my favourite type of writing is this kind the kind that allows me to use my own words, phrases and yes, spelling and punctuation. I like it because it's like my voice. It's distinctive. It's the closest you'll get to speaking to me. In fact, I'm a lot more eloquent in this format than face-to-face, so you're getting an even better version of me. The real me stumbles, stutters from time to time, and has been known to blurt out embarrassing information under stress. At least here, I have the ability to use the delete key.


And yes, this stupidly-long blog entry has been my own personal writing therapy, and next week I can go back to working on reference documentation without going crazy. Have a good week.


Comments (2)

  1. In my experience, editors aren’t writers, and writers aren’t editors. Then again, many so-called "technical writers" aren’t writers, but that’s a different post.I recently had this discussion at work. The sort of documentation my team

Skip to main content