Click here to monitor SSC
SQLServerCentral is supported by Red Gate Software Ltd.
 
Log in  ::  Register  ::  Not logged in
 
 
 

The Technical Nuances of Technical Writing

By Jamie Scharbrough,

You’re writing your first technical paper, or you’re preparing for a PASS chapter meeting. You’re doubtful that your work will make a good impression. Your paper doesn’t look quite…right.

Perhaps it looks right, but it sounds wrong when you read a few sentences to yourself. We’ve all been there, and I’m here to help. The advice here is fairly basic, but it can make a world of difference between thunderous applause and chirping crickets when you present at the next PASS meeting.

Grammar

Let’s start out with something simple. Grammar is one of those sneaky concepts that impacts your writing, in a large way. Your eyelids start to get heavy as you flash back to your freshman English class. You can’t remember what a dangling participle is. Heck, you can’t even remember how to find the subject and the verb of a sentence.

To that I say: relax. No one’s expecting you to be the master of grammar and dress up like Iggy Pop screeching about adjectives and pronouns with a bass guitar. (If you decide to pursue that route, let me know. I’d like pictures.)

For grammar, since we’re all geeks, I recommend www.grammarly.com. I used it a lot writing papers, and it works beautifully. It checks for prepositions, noun and verb issues, infinitives, modifiers, and over a hundred other issues you might miss. Grammarly offers a free 7 day trial, but I’ve found it does the job well and is worth the price. 

If you’d prefer something free, Ginger offers services online and for download, but it’s not as comprehensive as Grammarly. Either way, you can check your grammar without memorizing a preposition book or begging help from your old English teacher.

Sentence structure

One of the biggest issues I find in technical articles is sentence structure. Let’s say you’re reading an article about the MCTS 2008 70-432, and you come across this sentence: “The best way to study is to use Microsoft’s web site along with Pass4Sure, but this is I don’t think the best one, the best thing is practice.”

If that sentence caused you to blink and stop reading, good. You’re aware of how badly mangled it was. If you don’t think there was anything wrong with it, and you write, please get an editor. You need one.

In fact, if you’re a technical writer, I’d recommend an editor every time. It doesn’t even have to be someone who understands the language (although it would be helpful). All you really need is a friend who’s got a good eye and ear for how a sentence works. I don’t recommend a spouse or a family member, because they’re not going to want to hurt your feelings. You can also do this yourself, but a fresh set of eyes is better. You’re going to be weighed down by the time and care you put into the article; you won’t see it clearly. Have a friend look it over, and take a deep breath, because…you need to expect criticism.  

We’ve all had more experienced technicians correct us. In a way, this is no different. Your editor is trying to help you write the best article possible, and she can’t do that if you refuse to listen. If you’ve grabbed a non-technical friend who doesn’t understand all the jargon, explain it to him or her so he or she is not unnecessarily confused. Otherwise, keep your mouth shut and your ears open, because if you trusted this person enough to ask for help, you should trust them enough to listen to the suggestions.

Spelling

Oh, spelling. This is the trickiest of them all because a misspelled word can completely cause your audience to disengage, and you don’t want that. Unfortunately, your basic spell checker doesn’t get everything, or it skips over the incorrect homophone, so you suddenly wind up using “to” when you really meant “two”.

One of the best ways to combat spelling mistakes is to go over the paper line by line. Carefully prune the article, checking to make sure you’re not using the wrong homophone or an incorrect word. One more careful eye before you present or submit also doesn’t go amiss.

Flow and Paragraph Structure

When I was in college, one of my professors recommend the same structure-checking process for everyone, whether freshman or grad student. You can do this one on your own, but I’d recommend grabbing your friend again. If they’re reluctant, offer pizza. That usually works. Have your editor face you and read the paper out loud, slowly, one sentence at a time.  

This sounds weird, but as a general practice, it’s invaluable for grasping the flow and rhythm of the paper. You can hear where the paper breaks, where it jumps, and where it just moves along, seamlessly melding from one point to the next. Your first sentence in a paragraph should tell the audience what that paragraph is about, and your last should lead into the next paragraph.

You want that, especially if you’re giving a presentation. Doing this exercise helps you pinpoint the paper’s weakness. Best of all, if your friend is willing to read aloud, you can take notes at the same time.

Conclusion

I want to say a lot of this should be obvious, but I know techs, DBAs, and developers who are so eager to present and share their knowledge that they forget about the details that can help make their presentation more professional and easier to follow. Don’t be one of the people who forget, and don’t be afraid to ask for help if you’re still uncertain.

Total article views: 4319 | Views in the last 30 days: 1
 
Related Articles
BLOG

Big Data I: 16 Papers and original articles

  What are the most influential papers in the world of Big Data?  I suggest: http://bit.ly/BigData...

BLOG

Top SSAS white papers

These are my favorite SSAS white papers released by Microsoft, with many from SQLCAT.  I’ll keep thi...

ARTICLE

TSQL Challenge 62 - Break a long sentence in groups of 5 words

Read the input string and break each sentence into groups of 5 words. A row may contain more than on...

BLOG

White papers, DMVs and Monitoring Concepts

According to Jason Strate (SQL Server MVP) there are 5 white papers ever SQL Server DBA should read....

SCRIPT

Capitalize the first letter of a sentence

I created this script to capitalize the first letter of a sentence after a space. If no space in you...

Tags
career    
 
Contribute

Join the most active online SQL Server Community

SQL knowledge, delivered daily, free:

Email address:  

You make SSC a better place

As a member of SQLServerCentral, you get free access to loads of fresh content: thousands of articles and SQL scripts, a library of free eBooks, a weekly database news roundup, a great Q & A platform… And it’s our huge, buzzing community of SQL Server Professionals that makes it such a success.

Join us!

Steve Jones
Editor, SQLServerCentral.com

Already a member? Jump in:

Email address:   Password:   Remember me: Forgotten your password?
Steve Jones