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?
Comments
Guilherme said...
Thanks Jeff! I like it. =)
posted on December 15, 2009
nathan said...
ooo. th.at w’ere a reet gud read woz’nt it”"? tbx 4 tbat…
posted on December 15, 2009
David B. said...
Awesome read Jeff.
posted on December 15, 2009
David B. said...
OMG Nathan, ur soh 1337!!
posted on December 15, 2009
Mohammad said...
Important points.
$150 makes it obligatory to perfect your task of writing a tutorial.
Thanks Jeff.
posted on December 15, 2009
Design Informer said...
Amayzing, article Jeffrey. I really enjoyed it. Amayzing!
(Incorrect)
Amazing article, Jeffrey! I really enjoyed reading it. This is a great article that all bloggers should read. Thank you!
(Correct)
posted on December 15, 2009
Joseph Pecoraro said...
Excellent points. I hope I’ve managed to avoid most of these!
One thing that I think goes along with what you’ve pointed out about anchors is that #hash anchors are very useful! They are especially useful in technical documentation, which tends to be a lot of text thrown onto a single page. Developers can then pass around links to specific sections.
posted on December 15, 2009
admin said...
Hey, Joseph. So strange that you commented. I was literally just reading through your comments on the old 24 JavaScript Best Practices article from June. …Not for any real reason, other than boredom.
posted on December 15, 2009
Meshach said...
Wrong: thx 4 teh tut .. u r relly kewl.
Right: Thanks for the tutorial, You’re really cool.
posted on December 15, 2009
Sean Hodge said...
Great tips Jeff.
posted on December 15, 2009
Drew Douglass said...
Absolutely spot on Jeffrey, I’m sure you could take inspiration from half of the articles I’ve turned in to write this post! I’ve certainly made my fair share of these mistakes in my time writing for the web.
One thing I think I was always good about though was anchors, I totally agree with you point on anchors in articles. They are a convenience.
Great post, something all content producers should keep in mind.
posted on December 15, 2009
Yoosuf said...
Thanks @Jeff, it was really useful points and these are the are I am also doing mistakes
posted on December 15, 2009
Burak said...
Uh oh, I hope I’m not one of those people
English isn’t my first language, so I have an excuse
posted on December 15, 2009
Elijah Manor said...
I definitely need to brush up on these
Thanks for the pointers
posted on December 15, 2009
Ian Yates said...
This read like a piece of observational comedy! Funny because it’s true..
I love submissions by authors who I know can write well, markup correctly and take care with what they deliver; read once, upload, job done.
Saying that, you certainly taught me something. I didn’t realise that periods should be within the final quotation mark at the end of a sentence. You learn something every day
posted on December 16, 2009
Siddharth said...
I hope I am not making these mistakes.
Either way, I’ll keep these in minds for my future articles.
posted on December 16, 2009
VitaminJeff™ said...
Great article. I’m putting #3 to use right away.
posted on December 16, 2009
Louf Hawkner said...
This is a helpful beginner-level article, but just remember to take your research further if you intend to get paid for writing, or even more so, editing. The rules are “beginner rules” in that they are somewhat inaccurate but good enough to get newbies going.
posted on December 16, 2009
Jeffrey Way said...
@Louf – How are they inaccurate? I agree that they’re just beginner tips. Things like doing the proper research is expected.
posted on December 16, 2009
Rodrigo Flores said...
Great reminders Jeff! Good writing is definitely key for anything. It can make a beautiful website look ugly.
I just thought I would also point out that I think including periods or comas before or after the end-quotes might be one of those American v. Canadian v. British writers style issues.
Some people might just be used to one way, so as long as they are consistent there is nothing literally “wrong” with it.
Having said that, writing something for an international audience, we are better off sticking to what most people do.
posted on December 22, 2009
Matt Bridges said...
Thanks, Jeff! I will keep this post in mind if I intend to submit an article to you over at Nettuts+.
posted on December 27, 2009
The Digital Productivity Blog said...
I’d like to disagree about commas and periods with respect to technical commands.
Although the rules you cite are correct for general English, for tech publications, the specific format of a command takes great importance.
I try to keep the exact command inside quotes, without other cruft. Hence, this:
Type “ls -a,” and hit Enter.
Becomes:
Type “ls -a”, and hit Enter.
If a URL comes at the end of a sentence, I even put a space between the URL and the period so that linkifying can work correctly:
See http://example.com/somepage.html.
vs.
See http://example.com/somepage.html .
As the proportion of English text produced on-line increases in relation to printed publications, I think the generally accepted rules of English will shift, melding US and English (British) usage. This is especially in relation to quotes, because the Internet mentality is that the stuff inside the quotes is supposed to be a kind of canon.
posted on January 3, 2010
Abhilash Thekkel said...
Very important article for all newbies. Thank you for writing and posting.
posted on February 1, 2010