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.