Last time, I looked at Ken Getz’s well-written MSDN article on GDI (http://msdn.microsoft.com/msdnmag/issues/03/07/GDIColorPicker/). I covered the surface, the voice, and the structure of the article. This time, I’ll focus on the minutia.

Details

Ken is consistent about little things, like which words are capitalized and when, and how he refers to the various products in question. It’s true that an editor can help keep these things straight, but Ken’s personal knowledge of the approved form and his consistent use of them are part of why the article flows nicely. Notice that he says “dialog box” and not just “dialog.” That’s part of the secret to being consistent. He doesn’t use a nickname; he calls the object by its whole name throughout the article. The same holds true with capitalizing the names of objects and methods, and using the full names of products. If you’re not sure of how a particular word should be capitalized or if it’s okay to use a nickname, ask the product’s manufacturer. In Microsoft’s case, you can usually troll MSDN for references. Be sure to look at several different articles because there are often conflicting versions. If you find a conflict, all you can do is make your best guess and be consistent within your own work. The Microsoft editors can easily do a global search and replace if you got it wrong. You can also look at a dictionary, Microsoft’s Computer Dictionary, or a style manual (see my blog on Useful Books). You may not find the exact term, but you might find a parallel one. If there’s a style sheet (see my blog on style sheets), be sure to enter the questionable term and your source. Typically, you can use the UI screens to get some idea of what is acceptable, but text files are often held to a higher standard than UI screens. (I don’t know why UI screens don’t seem to get edited.) As long as you are consistent within your own work, an editor (or you) can go back in easily and make global changes if need be.

Word Choices

As I mentioned in Part 1, Ken also doesn’t forget that he’s writing to one person at a time. He doesn’t switch from saying “you do this” to “we do this.” He knows that with only one name in the byline, he can’t say “we did this,” which is a fairly critical point. Unless you have multiple personalities or are representing your company anonymously, one name in the byline means one writer. Either take yourself out altogether, or be sure that it’s just you and that one reader throughout. Ken also avoids jargon. He makes no attempt to be hip or trendy, and because of that, he seems really in the know. Isn’t that a fun contrast? Ken also avoids unnecessarily complex language. It’s part of the cube-next-door persona, and it works like a charm. It’s because he has a huge vocabulary that he knows he doesn’t need to rely on obscure words to sound like he knows what he’s talking about. It’s another fun contrast. Ken doesn’t use a lot of caveat words (however, thus, clearly). This means that he talks about the subject without waffling. He says something works or doesn’t without hedging. Rather than softening the blow, caveat words obscure the meaning, so Ken avoids them. When Ken introduces a new term, acronym, or concept, he is sure to mention it again shortly after. Even though he has that whole first section to introduce new terms, he reminds readers of the context soon enough that we don’t have to search around for the reference. If several pages pass before he uses a new term again, he just redefines it, either by context or parenthetically. I suppose it’s a form of hand-holding, but it means that readers don’t spend time scuttling around looking for a previous usage in order to follow the discussion.

The Introduction and Conclusion

In the Introduction, Ken says exactly what readers will know after reading through the article. He names the areas. It could have been a little stronger if those areas were also named in subheadings. The Conclusion restates what the tool does, points to the lessons learned, and points out that a little creativity can extend the tool much further. It adds a little personality, implying that readers might be feeling tired of their familiar patterns, but doesn’t change to a new voice entirely. Both the Introduction and Conclusion are very strong. Ken has used these sections to tell about the pairs in the article: what we will learn and what we did learn, who will benefit from reading this and what skills they require, and what we knew already and how that works in this new system. Conclusions are often awkward, probably because by the time you get there, you’ve spent all your “real” thoughts about the subject at hand. Try imitating Ken. What he does is produce an abstract—a summary—of the product as if he were trying to sell the idea of reading the paper. He draws from the topics he covered, pointing back to the article, and he cites ways that his readers can apply their new knowledge immediately. He also uses slightly more marketing-appropriate language than he used in the rest of the article with expressions like “break out of the RGB rut” and “powerful features.” This slight change in voice helps the reader know that the article is over. Okay, Ken, you can berate me for singing your praises in public, right in front of you. I’m sure my readers agree that you wrote yet another good article, and that your work is a good place to steal healthy writing habits.