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.