You are here: Home / Blog / Rant: I’m not dumb – Expanding Acronyms and Third Person Nouns

Rant: I’m Not Dumb – Expanding Acronyms and Third Person Nouns

4th April 2012 by 9 Comments

It is part of my professional life to write documents and whitepapers. I do this both for my $DayJob as a Network Engineer/Architect, and for my $NightJob writing whitepapers and articles for vendors and analyst firms ( /tout feel free to contact me for details – /tout ).

Over time of submissions, I’ve had my content reworked in ways that I don’t agree with. I think it’s time to recognise that the English language changes over time.

Acronyms

Some people believe that acronyms like “IETF” should be “Internet Engineering Task Force (IETF)”, or “OSPF” -> Open Shortest Path First (OSPF).

Two things about this. One, I’m not in high school any more where I’m required to demonstrate my knowledge so that the teacher can judge, and mark, my paper. Second, writing a technical paper on a technical blog for a technical audience inherently designates that the audience knows about technology. This isn’t some news paper that gets read by people who failed school and/or got liberal arts degrees printed on toilet paper. If the document uses a new technology with a shiny acronym then that should be explained, but acronyms that have been in use for twenty years don’t need an explanation. Right ?

Possessive Nouns

It’s a University or academic conceit that a technical topics should be written in the Third Person. Instead of

Once you have completed the network analysis, the results can be compiled into a table so that the team can analyse the outcomes. Take the time to consider your results and check that they match your expected outcomes.

At the completion of the Network Analysis process, the results can be compiled into a table for team review. Results should be reviewed against the hypothetical baseline case that was established during the Gap Analysis in the initial engagement.

Which of these is more readable and usable. The second version is certainly pretentious and full of pomposity, but the first version is much more usable.

The EtherealMind View

It’s time for people to consider their target audience and write accordingly. So much design documentation is well done, and grammatically pure while also remaining unreadable. Having worked for a reseller for ten years, the time I wasted on spelling and grammar instead of content and diagram still pains me.

Focus on writing content, and less on the presentation. Stop correcting spelling errors and focus on IP routing and Network Diagrams.

Rant over.

Disclosure

I have nothing to disclose in this article. My full disclosure statement is here

Filed Under: Blog, Rant
About Greg Ferro

Greg Ferro is a Network Engineer/Architect, mostly focussed on Data Centre, Security Infrastructure, and recently Virtualization. He has over 20 years in IT, in wide range of employers working as a freelance consultant including Finance, Service Providers and Online Companies. He is CCIE#6920 and has a few ideas about the world, but not enough to really count.

He is a host on the Packet Pushers Podcast, blogger at EtherealMind.com and on Twitter @etherealmind and Google Plus

  • http://www.firstdigest.com/ Calin C.

    You got complains about how you write your blog or how did you arrive to this post (which is great btw)?
    In my opinion, the person which analyze the grammatical correctness of a tech blog rather than its content, is definitely in the wrong place.  

    • http://etherealmind.com Etherealmind

      In this case, no. The motivation comes from another project where the reviewer was insisting that all these things should be done, while I was pointing out how unreadable it was, and how much time was being wasted.

  • http://showbrain.blogspot.com Ben Story

    While I agree that some acronyms shouldn’t need defined at first use, I wonder though if they still should be.  Especially when doing network documentation, I don’t make the assumption of technical knowledge level.  Unfortunately the person who may need the documentation may not be a real network engineer. They may have been thrust into a bad situation because they happened to be technical in a different area and the organization was without a true network engineer due to illness, job churn or other reasons.  I try to remember how confused I have been at each change in vertical trying to learn the new lingo.

    • http://etherealmind.com Etherealmind

      Whlle that is very true, how much time did _you_waste getting that documentation to that level. I suggest that your time is more valuable, and that the reader can be assumed to have some expertise.

      • http://showbrain.blogspot.com Ben Story

        I don’t consider it wasted in my environment because I’m the only network engineer in the company. I put this type of documentation into my red folder that is labeled “If Ben Gets Hit By A Bus”. In a sense it’s my network’s continuity plan if I were to die tomorrow. I do it for the same reason that my previous employer didn’t like too many people from the same IT team being on the corporate plane together.

  • Pjgalligan

    Another option to defining acronyms is to have a glossary, but then you have to make sure every acronym appears in it or your reviewer will get the red pen out on your glossary. Plus, it probably takes just as much time. Besides, everyone knows how to Google right? As you say, write for your intended audience, and I usually define the intended audience and assumed level of knowledge at the start of a document.

    I prefer this:

    “Once the network analysis is completed, compile the results into a table. Analyse the results and compare to the expected outcomes.”

    to either of the options you quoted.

  • http://BladesMadeSimple.com/ Kevin Houston

    I’ll play Devil’s Advocate here – put yourself on the other side of the arguement.  Imagine putting out an RFP as a customer and receiving responses with incorrect spelling and foreign acroynms.  It may have some great ideas and architectural diagrams, but if the document is littered with incoherent thoughts, wouldn’t that discredit your architectural thoughts and reflect a potential lack of detail that could be reflective in your overall vision / solution? 

    I agree with your thoughts about technical documents are written for technical readers, but spelling out your acronyms – at least those that may be “common” could save your reader a few extra seconds and keep them engaged in your paper instead of sending them off to get distracted by searching for an answer.

  • Ralph

      The first time you use the acronym in an article, I think it best to also expand it. Subsequently, just use the acronym. This avoids potential confusion with very little effort on your part. For example, in semiconductor engg RTA usually means Rapid Thermal Annealing, but I once wrote a paper on the relaxation time approximation, which for semiconductor theorists is the more common expansion of RTA. Now imagine a semiconductor theorist writing to an engineer. It happens.
      The more pretentious example you gave is more typical of MBAs than university profs today. We write in first person, and generally do not use the passive voice. E.g. “We have developed a new algorithm….” became perfectly acceptable in technical articles around 1980, although it may have been different earlier, say in the 60s. Of course I know only about articles in physics and engg.
      I strongly disagree with you on grammar and spelling. The occasional typo is fine, but as Kevin pointed out, poor grammar and consistently poor spelling shows a lack of attention to detail, and rightly so. I have found an excellent correlation between students’ performance on technical projects and the writing (grammar + spelling) in the reports they submit as part of the project. I do not penalize bad writing and restrict myself to snarky remarks, since I’m not their English tutor. Still the correlation is surprisingly high.

    • Ralph

       ”poor grammar and consistently poor spelling show (not shows) a lack of attention to detail”. Silly me, talk of the devil quoting the scriptures.