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.
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 ?
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.
This NOT meet approved english style that removes all of the pronouns and first person. Like so:
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.
I have nothing to disclose in this article. My full disclosure statement is here