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.
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.
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#
Investigating the Sample App
Drawing the Color Wheel
Finishing the Drawing
Painting on Demand
Repainting is Expensive
Investigating the Sample
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.