Melanie Spiller and Coloratura Consulting

Copyright 2020 Melanie Spiller. All rights reserved.

Analyzing Good Writing, Part 1

Melanie Spiller and Coloratura Consulting

Although he will be embarrassed by my lauding his praises in public, I’d like to use one of Ken Getz’s MSDN articles to guide you through a look at some good technical writing. Here’s the address for the article in question: http://msdn.microsoft.com/msdnmag/issues/03/07/GDIColorPicker/

Looking at the Surface

It’s a little long, but the title says what’s in the article. The title says that the article is for beginners and that is not comprehensive (that’s what primer means), it says what tools you’ll use (GDI+ and the languages), and it says what you’ll know at the end. As you read through, you’ll see that Ken only talks about the basic aspects of using this tool. No tangents and no apologies: just right to the point and then out. The title also tells us that he won’t be clever or cute. He’ll just tell us what the tool does. If you run a word count, you’ll see that the article is about 5100 words. MSDN articles are typically 5000 words, and Ken is in the ballpark here. If you want a brief summary that leaves you understanding what the tool does without a lot of marketing jargon or preening, that’s what you’ll get in 5000 words on a complex subject. The next thing you can easily notice without reading a word, is that Ken has interrupted the text about every page or page and a half with an image or with code. Images, code, sub-headings, tables, bulleted lists, and step lists are all welcome resting places for readers who need a break. These breaks lead an interested reader into the text and prevent reader fatigue. Visual interruptions invite the reader to look at the material in several ways. People learn in many different ways—some need the words, some need the images, some need sounds, some need to touch it somehow or do the task themselves, and others can follow a strictly conceptual philosophical discussion. You can’t address every way of looking at your subject, of course, but Ken covers concepts, doing it, and images with these little interruptions. Now, look at the sub-heading frequency. The first section is fairly long--about six pages. There may have been no suitable interrupting sub-heading in the approved outline, but six pages is a bit long. Fortunately, there are plenty of images in there, but if your topic isn’t as readily illustrated, you’ll want to find a few lower-level sub-headings. After that first stretch, the intervals are one to three pages between sub-headings, which seems about right. More than that might be irritating and unnecessary; less might leave us without a good resting point. You can certainly use deeper levels of subheadings than Ken did in this article, especially if your topic warrants it. Ken was trying to stay near the surface, and his sub-headings show that he did. (When we start reading the text, you’ll see that the first section sets the scene, so he wrote the section all of a piece. The rest of the article puts these concepts to use, so he broke it up logically. Clever, eh?) Ken’s paragraphs are fairly uniform in length and they are uniformly long. Less experienced authors should make a point of writing shorter paragraphs in general (less likelihood of tangents), and if you do write a long one that can’t be broken into smaller bits, be sure to put plenty of short ones all around it. Long paragraphs are daunting. People like “white space” in their reading, even now that we’re reading on screen instead of in a book. White space allows readers to assume that they can consume the material in digestible chunks before they ever read a word. On the other side, putting every second sentence into a new paragraph is too much interruption by white space and shows that you perhaps don’t know when to start a new paragraph and when not to.

Voice

Now it’s time to read a little. In the first paragraph, Ken refers to himself in the first person (“in this article, I’ll provide a sample…”). He doesn’t spend any time at all thumping his chest or proving his qualification, he just lets us know that he is going to tell us his own experience of this product, rather than a more sterile narrative. Microsoft often wants authors to pull themselves out of the work, so that sanctioned publications all seem to be coming from the one corporate source. Unless you have a large reputation as a developer and author and speak at a lot of Microsoft-sponsored events, you can save yourself the pain of a brutal edit by removing references to yourself. (Ken has sanction.) If you’re writing for a magazine or an online publication, and that publication encourages personality, go ahead and write yourself into the article. But otherwise, it’s important not to distract from your topic by being too personable. People don’t expect—or want—a book or article on application development to be an autobiography. Ken also talks to the reader directly. He says, “you can do this” and so forth. He doesn’t get distracted by the fact that there will presumably be many people reading the article, and acknowledges that each reader reads alone. He also doesn’t include himself in the reader’s activities by saying “let’s” or “we’ll.” He says “I did this, and you can too,” as though he’s talking to a single person and not a classroom. There’s a friendly, cube-next-door tone throughout the article. Ken is very good at making complex subjects seem accessible this way, but less experienced authors should be careful with this tone: it can seem condescending if you don’t get it just right.

The Structure

Here’s how Ken’s article looks in outline form. A Primer on Building a Color Picker User Control with GDI+ in Visual Basic .NET or C# Color Spaces Investigating the Sample App Converting Colors Drawing the Color Wheel Finishing the Drawing Painting on Demand Repainting is Expensive Cleaning Up Investigating the Sample Conclusion Yes, that’s a little dull. It’s possible that Ken played with these headings until he came up with something that felt right, but looking at the structure, it’s more likely that he built the sample application and then wrote the article around it. He could have put in a few lower-level sub-heads, and he could have made a more obviously direct path to the conclusion, but as you read the article, I don’t think you’ll be distracted by any out of place topics. Because he used the solid method of writing the code first, which is his strongest strength, his article followed a similarly logical route. The outline reflects how he coded. This means that the global structure is chronological (see my blog on Organizing Principles). Let’s look at a few paragraphs and see whether he stuck to that at a more atomic level. In the first paragraph after the introduction, Ken tells us that he is limiting his discussion to two aspects of the product, and within those, only covering those topics unique to the product he’s describing. He also provides us with some basic terminology without making us feel like we must be idiots not to already know. That’s a pretty good trick to imitate. He gets all the readers on the same page, no matter what their expertise level. That first paragraph followed the structure of the screen he describes (the Space, Time, or Function structure). For the next several paragraphs, he continues discussing this one screen and the effect the changes to various components might have. Any tangents he takes are directly relevant to covering the screen’s components, but they also serve to introduce new topics and terminology. Ken really packs a lot into each paragraph! Next, Ken tells about one of his mistakes before he knew better. This interesting vignette shows us he is human and didn’t always mystically program miracles, but it also introduces the next set of interesting topics. This is a literary device straight from fiction. When the text was getting a little dry, he killed off his protagonist, so to speak. In the next paragraph, Ken gets back to the screen in question, using the lessons learned from the vignette. He also goes back to the Space, Time, or Function model. Each time he introduces a new image, he uses the Space, Time, or Function structure. Right after Figure 5, Ken tells another story about his own discovery process. He uses this pause from the structural discussion to introduce the less linear part of the discussion, and the main part of the article. From then on, Ken is fairly chronological, talking about building the sample application and the functionality issues that arose. Every now and then, he steps into his personal journey, but for the most part, he guides us down a generic path. Although the global structure is chronological, the interior structure seems to be Space, Time, or Function with occasional personal (and chronological) breaks. In the next blog, I’ll discuss the details of Ken’s article, including word choices, capitalization and product names, and the introduction and conclusion.