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.