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.

  • 2330 views

  • Rate
    [Total: 5    Average: 5/5]
  • Ross Presser

    In this particular post, there were three opportunities for an oxford comma, and you only used one. 🙂

    Oxford comma present: “fixing spelling mistakes, adding Oxford Commas, and thwarting an author’s ambitions to end a sentence with a preposition.”

    Oxford comma absent: “only the specific, precise and meaningful.”
    Also absent: “thoughts, ideas and experience it contains …”

    • Andrew Clarke

      (editor) You’re hired as proofreader, sir.

  • Peter Schott

    I’ll admit that I struggle with brevity. I want to include details, but find it difficult to simplify and reduce my text. Sadly, that usually ends with me being more like Polonius right after saying, “as brevity is the soul of wit.” 🙂

    I do try to include the Oxford comma, though. Not seeing it when it should be there always irks me.

  • Sinisterpenguin

    I couldn’t agree more – you can’t just slap a few words down on a web page or Word doc & say “done”.

    Any well written piece is a lot of work – blogs, documentation, even whole organisation e-mails. Often ignored technical writers & editors need a pat on the back.

    Keep up the good work & maybe we can kiss goodbye to tldr;

  • I’m one of those technical people who find it very hard to express myself clearly. Good writing requires order, sequence, and a strong narrative, whereas most people want to write in either a clenched-teeth textbook strangulated style, or else, by contrast, want to emulate ‘Catcher in the Rye’ with flashbacks, asides and alternative universes. Paradoxically, well-ordered writing is very tedious to read. A good bit of writing, whether a short note, article or book, usually represents a titanic struggle between order and disorder -editor and author. It is in the interest of the reader that neither side should dominate. I have to say that Tony has many times transformed my work into a far more palatable form. Like all good editors, he has the knack of working out what I really meant to say. He is also deft in placing those Oxford commas.

  • Sean Redmond

    When I’m writing documentation, I write for an audience of people who are interested but new to the field, for example, the newly-started DBA. I can’t expect this person to know the business logic, nor to immediately understand why I’ve used the construct that I have used. However, I assume that they know they basics — they know what tables, joins, views, inserts, updates & deletes are.
    I work on the principle that if I can’t explain something simply and clearly, then I don’t really understand it myself.
    p.s. I find the artificial distinction between «it’s» and «its» annoying. The apostrophe indicates that a letter (most probably an «e» or a schwa) has been dropped sometime in the past. Genitives have an apostrophe to indicate the dropped letter and the contraction of «it is» has an apostrophe to indicate the dropped «i».
    p.p.s. My working definition of an editor is one who reads texts like Fowler’s and applies it to their daily work.

  • j_lowery

    “If you’re interested in improving these skills, through technical writing, let us know.”

    Yes. Yes, I am.

    • Gina Taylor

      That’s great! To find out more about becoming a Simple Talk author, drop an email over to editor@simple-talk.com.

  • hakim.ali

    As a developer who sometimes writes technical articles, I am aware of the conflict between brevity and detail, and the art of extracting meaning from chaos. I am very thankful for some of my co-workers who have agreed to edit my writings. One more vote for ‘… improving these skills, through technical writing…’. Cheers.

  • This post goes a long way to proving the old adage… that there is dignity in all work. Surely that must be true if it is true of technical editing.

    I jest, of course. There is indeed dignity in a respect for one’s trade and a commitment to quality. Simple-Talk has always set itself apart from other technical publications in terms of quality. Having a skilled and committed technical editor has surely played a significant role in your success.

  • TodConover

    Your post got me thinking about “editing” in the IT world. Not articles, but projects. How often have would-be authors (users) come up with ideas for articles (projects) that sound OK at first, but rapidly wonder all over the place and loose there way. There needs to be an edit process. Truth be told, I’m old school. I come from an era where we had specifications and they got edited, but those things take time. Now-a-days there’s a lot of winging it going on and not so much editing. Articles (projects) don’t read quite as well as they once did. Many more short stories being written and not so many good novels. I think we’ve lost something along the way.

  • Keith Rowley

    My English degree has been a thousand times more valuable in my work as a DBA than my minor in computer science.

  • I disagree with the Oxford comma. Fite me IRL.

    Those silly images of JFK, Stalin, etc. Are not arguments. They don’t say what the pictures represent. Two things: b and c. Add a third? Put it plus a comma: a, b and c. End of story.

  • alan.silverblatt

    I guess I’m sort of odd as a developer, as I actually ENJOY documenting the work I do. For me, producing clear, concise and accurate documentation is just part of getting the job done right. Whether it’s a manual for the end user or technical specs to aid other members of the IS team, producing quality documentation is just as satisfying to me as delivering a reliable and well designed application.

  • rogerthat

    I agree that all writing should be done well. When it isn’t, at best it is grating on the nerves (akin to hearing buffet pronounced “buff-it”), at worst, it truly makes learning more difficult. In technical programming / database topics, I am much more concerned with technical accuracy over how something is written.
    With the growing popularity of Agile, documentation is on a distinct decline – at least, documentation that doesn’t fit on a 3×5 card…