6 Most Common Tech Writing Blunders
I edit tutorials and articles every single day of the week for Nettuts+. While I do have a handful of authors who write perfectly well, there are countless others who submit somewhat baffling tutorials – baffling enough to make me ask, “Did you even read this before you submitted it to me?”
Now, I’m not by any means a world-class writer. I’m sure I make plenty of mistakes; in fact, I guarantee as much. Having said that, I do think I have a relatively firm grasp of the language. If I could force my writers to adhere to these following six steps, my days would be much easier!
1. Proofread!
This one should go without saying; yet still, I repeatedly find myself proofing articles which contain numerous errors that anyone could spot. For example, we offer a base tutorial template on Nettuts+ for our writers. For the intro paragraph of this template, we placed a few generic sentences as an example.
Then we write a short introductory paragraph. Not more than a few lines, this appears on the blog index page next to the preview image.
You wouldn’t believe how many submissions we receive each week which contain this exact text. Mindless omissions like this can easily be avoided. Needless to say, if authors won’t take the time to even read the opening paragraph, I can’t trust that the entire tutorial is Nettuts+ worthy.
2. Using the Same Line Over and Over
In defense of our authors, tech tutorials are difficult to write – for anyone. They’re mostly boring, and leave little room for creativity. With that said, I often look over tutorial submissions, where, quite literally, every new paragraph begins with something along the lines of “As you can see…”
But wait – the same is true for the opposite! Just because you’re about to paste in a block of code doesn’t mean that you must preceed said code block with “Let’s do that now…” Occasionally = not a problem. Dozens of times per tutorial = no thanks!
3. Using Commas Incorrectly
As a tech editor, I’m much more forgiving in this area. The rules differ from country to country, and, let’s face it, who really cares whether the comma should be placed inside or outside of the quotation mark. It’s a tech tutorial, not a novel! Furthermore, it’s highly unlikely that a talented developer will also have comparable writing skills. Having said that, there are simple guidelines which only take a few moments to memorize. Most notably: learn when and where to place your commas and periods. For example:
Incorrect
In response, the dog said, “thank you for the treat”.
The line above is grammatically incorrect. Can you spot where? … The error comes from that period at the very end. Instead, it should be placed within the quote.
Correct
In response, the dog said, “Thank you for the treat.”
Also, note how we’ve correctly capitalized the first letter of the quote. Now for another example:
Incorrect
“Shall we go shopping”, the girl asked?
There are a few mistakes above.
- As the quoted girl is asking a question, we should conclude the quote with a question mark.
- Commas generally go before the closing quotation, however, when the quote ends with a question mark, we omit the comma entirely.
- Although the quoted sentence is a question, we’re still making a statement. The final question mark should be replaced with a period.
Correct
“Shall we go shopping?” the girl asked.
4. Writing 2 Instead of Two
Unless the number is used in a title that is meant to grab the reader’s attention – much like the title of this particular posting – always replace the number with the full written word. 5 becomes five. 8 becomes eight.
Incorrect
Nothing signals an amateur writer more than sentences such as, “I’ll show you 2 ways to fix that error.”
Correct
I’ll show you two ways to fix that error.
5. Look for the Red Underlines
Sometimes, late at night, when I find myself scrolling through a tutorial submission, searching for red underlines – signaling a misspelled word – I secretly punish the author with words that he or she will never hear. How difficult is it to perform a quick spell-check? To not do so is lazy, and inconsiderate.
6. Anchors are your Friends
This one is absolutely a pet peeve of mine. Never take for granted that the reader knows more than he or she actually does. While a framework, such as CodeIgniter, might be an every-day word for you, the same may not necessarily be true for the reader. Additionally, it’s a common courtesy to provide links to the tools/articles/services that you reference. Why force the reader to perform a Google search?
It’s time consuming, and might take the writer out of his flow, but take the extra moment and wrap the word within anchor tags. Don’t make me do it for you! 
Incorrect
Recommended Tools
- Skitch
- 1Password
- Echofon
- Coda
- The Hit List
Correct
Recommended Tools
Conclusion
As mentioned in the opening paragraph, I’m in no way a flawless writer; I’m sure I make numerous mistakes. But the simple errors listed above occur far too often. Which ones did I miss?
Jeffrey,
I know this is an older post, but I just read it tonight. I’m a Nettuts+ fan, but this is my first visit to your blog.
Jakob Nielsen argued for the use of numerals online as early as 1997. In 2007 he reported on eyetracking studies that back up his advice. The studies show that, “numerals often stop the wandering eye and attract fixations, even when they’re embedded within a mass of words that users otherwise ignore.” (http://www.useit.com/alertbox/writing-numbers.html)
We don’t read online content. We scan it. The fixation Nielsen describes makes numbers more memorable. They also shorten sentences and paragraphs. That’s usually considered a best practice for online text.
I did a quick online search. Many technical writing style guides don’t differentiate between printed and online text rules about numbers. But I found 2fs with contradictory advice.
A Purdue document titled “DM Best Practices: Writing for the Web” states: “When writing numbers, particularly as they represent facts, use numerals instead of words (i.e. 5 instead of five)”. (http://www.its.ipfw.edu/training/00-dm-webwriting.pdf, Page 13)
A document titled “Writing for the Web: Content is King” by the University of Buffalo’s School of Management disagrees: “Spell out whole numbers below 10 and use figures for 10 and above.” (http://mgt.buffalo.edu/files/internal/School%20of%20Management%20Editorial%20Guidelines.pdf, page 3)
Regardless of Nielsen’s recommendations, it pays for a freelance writer to find out what the customer wants!
Excellent post.