Simple Talk is now part of the Redgate Community hub - find out why

The Oxford Comma and Me

Many people in IT, even at Redgate where I work, see the job title “Editor” and think I spend most of my time fixing spelling mistakes, adding Oxford Commas, and thwarting an author’s ambitions to end a sentence with a preposition. They are sometimes bemused, therefore, when they learn how long a proper technical edit can take, and what’s involved.

Punctuation and grammar are only a very small part of it, and certainly not the part I find fun or interesting. Not that the rest of the job is full of glamour, but it can be challenging and rewarding.

I devote a lot of energy to pinning down text to only the specific, precise and meaningful. I spend too much time asking authors to explain to me the precise subject to which their “it” refers, and gently discouraging use of non-specific nouns such as “thing”. Even the best authors find the occasional slide towards the non-specific hard to resist. I’ve lost count of how many times an author has suggested that the reader “test out different scenarios in their own environments“. I used to agonize over exactly what “scenarios” played out in this author’s “environment”, but I’ve since learned that it’s a greater kindness just to hit the delete key.

I also test code, challenge lazy technical assertions that don’t seem substantiated by fact. I remove hyperbole; an author may wish to refer to a “game changing” or “groundbreaking” new feature, but post-edit they find that it’s just a “new feature”, after all. Not that I take (much) satisfaction from dampening high enthusiasm, but it needs to come out naturally in the proof of what the feature can do. I restructure and reconstruct to bring clarity and order to the author’s sometimes brilliant but often chaotic ideas.

It can be hard and occasionally frustrating work for both editor and author (ask Grant Fritchey). What’s the payoff? I like to tell the story, as it’s a touchstone for me as an editor, of Woody Allen at his most daring and misanthropic, working away on a messy, chaotic and seemingly ill-fated film called ‘Anhedonia’. In the quiet period after the shooting stopped, his editor, Ralph Rosenblum, helped Woody find amidst the chaos a very funny and moving story. The film was released as Annie Hall.

It’s a process that applies to technical text too, at least when I’m the editor. Gradually, through a series of many incremental adjustments, the text becomes more specific, and “embodied in the particular”. It gains clarity, loses its ability to mislead or confuse. In the best cases, what emerges from this process, shining into the light, is the real “story” that the author wanted to tell. The thoughts, ideas and experience it contains are revealed for all.

Just occasionally it’s a story a lot of people wanted or needed to hear, and the results have sometimes been spectacular. The article or book reaches hundreds of thousands of readers. Reputations are made, MVP awards bestowed.

In fine art, a large part of training is given over to explaining your work and, in effect, promoting it. Similarly, all sorts of techniques and rules go into explaining technical concepts, and putting your views across with clarity. I wonder occasionally why such skills aren’t part of IT career training. If you’re interested in improving these skills, through technical writing, let us know. They are surprisingly relevant for all development work.

Commentary Competition

Enjoyed the topic? Have a relevant anecdote? Disagree with the author? Leave your two cents on this post in the comments below, and our favourite response will win a $50 Amazon gift card. The competition closes two weeks from the date of publication, and the winner will be announced in the next Simple Talk newsletter.

How you log in to Simple Talk has changed

We now use Redgate ID (RGID). If you already have an RGID, we’ll try to match it to your account. If not, we’ll create one for you and connect it.

This won’t sign you up to anything or add you to any mailing lists. You can see our full privacy policy here.

Continue

Simple Talk now uses Redgate ID

If you already have a Redgate ID (RGID), sign in using your existing RGID credentials. If not, you can create one on the next screen.

This won’t sign you up to anything or add you to any mailing lists. You can see our full privacy policy here.

Continue