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

The Voice of the DBA

Steve Jones is the editor of SQLServerCentral.com and visits a wide variety of data related topics in his daily editorial. Steve has spent years working as a DBA and general purpose Windows administrator, primarily working with SQL Server since it was ported from Sybase in 1990. You can follow Steve on Twitter at twitter.com/way0utwest

Writing Technical Articles - A Few Simple Tips

A few simple tips that I've learned over the years. Keep these in mind as you write your next article.

That and Which - It's amazing how often I correct this in writing, and it was something I learned early on. If you use "that" in a sentence, you don't need a comma. If you use "which", you do. A few samples:

  • The DMVs are system views that allow you to gain insight into the server operation.
  • The DMVs are views, which give you insight into the server operation.

There are a few other rules here as well. That should be used for essential clauses, meaning the are necessary in the way things are worded. If you have non-essential clauses, like descriptive information, use "which."

If you use "that" in one sentence, or earlier in the paragraph, you can switch over and use "which" for the sake of better flow.

Its vs. it's - I still mess this one up at times, but here is an easy way to read your sentences and avoid mistakes. Replace "its" with "it is" when reading. If it makes sense, you're supposed to be using the contraction "it's" and not "its." If it doesn't make sense, as in it's possessive, then stick with "its."

  • I have found it's important to test the boundary cases. (Test: I have found it is important to test the boundary cases)
  • In this particular boundary case, its result is zero. (Test: In this particular boundary case, it is result is zero. Doesn't make sense. stick with "its")

Capitalization - Surprisingly this is more difficult than it seems. Proper nouns and names are capitalized, and of course, the first word in a sentence. Outside of that, don't capitalize random words. So SQL Server is the proper name of a product, but "the database server" is a generic. Don't capitalize "Database Server," which is something I see often. The same thing applies for groups, even if you think they're specific. I realize you are talking about your "development team" or your "manager", but unless you call them out by name, or you are using the title of the group, they aren't capitalized.

If you've got questions, post them in a comment and I'll try to answer them. I'd also recommend that if you want to write, pick up a style guide. Microsoft has published a technical one and the Chicago Manual of Style is always a good book to keep around.

The best advice I can give you is to have someone else look over your article. I realize that I don't always do that for my editorials, and some of that is because of the time pressures and crunches I get under to get things done, but for technical articles, I'd be sure that you have a friend read it.

Comments

Posted by Robert Pearl on 26 August 2009

Thank you Professor Jones :-)

Posted by Steve Jones on 26 August 2009

:), I'm not sure I'm ready to be professor. Maybe Teaching Assistant Jones.

Posted by jcrawf02 on 26 August 2009

Steve, good series so far. Looking forward to the Part 3 on Where To Publish. You sort of mention it in Part 2 when you mention focus, focus, focus; but one of the things that was really highlighted in a recent writing class I took was how you can probably cut about 20% of what you write from your rough draft before you reach a final version. If you are just adding words to add words and not further your point, get rid of it. (like that whole last sentence)

Also, know your audience. Are you writing a beginner article for me? An advanced article for Itzik Ben-Gan? An editorial? Choose your writing style appropriately.

Thanks for the tips, someday I'm going to submit an article to you, and you can redirect me here for corrections. ;)

Posted by Anonymous on 26 August 2009

Pingback from  Twitter Trackbacks for                 SQL Server Central, Writing Technical Articles - A Few Simple Tips - SQL Musings         [sqlservercentral.com]        on Topsy.com

Posted by Steve Jones on 27 August 2009

Sorry about part 3. It's been in draft, and I'm struggling to get caught up on some writing. I'll put it out soon!

Leave a Comment

Please register or log in to leave a comment.