Eric White's Blog : Writing

Writing for Professional Developers

EricWhite — Wed, 22 Oct 2008 21:24:00 GMT

If you are a writer, there is no substitute for making writing and language a focus of intense study. When you write, you don’t want anything to obstruct your message. Bad writing, more than anything else, will prevent your readers from learning what you intend to communicate. This post presents a few of the principles and guidelines that I use when writing for professional developers.

Answer the Three Important Questions

What are you going to say? What is your message? What are the key takeaways?
Who is your audience? What do they know? What don’t they know?
What is the style/form? Is it academic / formal / informal?

Regarding audience, I have the opinion that the vast majority of documentation written for programmers should be written for professional developers. Beginning and journeyman developers have their own sub-genre.

Be the Reader

When you are writing, you must be two people. First, of course, you are yourself as the subject matter expert. But at the same time, you must ‘project’ yourself into your reader’s mind. If you write something that your reader won’t understand, this should be picked up by you when you are ‘being your reader’. Same thing if you use an acronym that you haven’t introduced yet, and isn’t a common acronym.

The definition of empathy is the ability to sense and understand someone else's feelings as if they were one's own. In the case of projecting ourselves into the minds of our readers, we want the ability to sense and understand our reader’s thought processes as if they were our own. As they read your document, answer their questions as they come up. If you can do this, the battle is two thirds won.

This was one of the reasons I was keen on writing the functional programming tutorial shortly after I learned functional programming using C# 3.0. I was writing for myself, but myself as I was a few months earlier.

Tell Stories and Analogies

If your format allows, a story always makes the writing memorable.

Many years ago, I was writing a magazine article about detecting heap corruption when developing in C. Those were the days when memory protection in operating systems was not common. One of my writer friends suggested that I could use the analogy of putting a fence around the data, and detecting and reporting that the fence had been pushed down. I received more comments about those few sentences than I did for the rest of the article. Readers appreciated the vivid image. Since then, I have always tried to put stories and analogies in technical articles.

Some formats, such as documentation and whitepapers don’t always lend themselves to inclusion of stories.

It’s all about the code

When explaining something to other developers, there is nothing that communicates better than a good example. This serves two purposes – the example shows exactly how the API / language feature should be used – and the example can be copied and modified by the reader. Studies show that this is exactly how professional developers work – they find a working example, and modify it for their purposes. Craft your examples with this in mind.

I had a goal for the LINQ to XML documentation – every topic (class, method, property, and event) in the reference would include an example. And all appropriate topics in the conceptual material would include a more substantial example. Fortunately, I had a manager who believed in this too, and gave me the time and resources to do so.

But this isn’t possible without an approach in place to test snippets and samples in a systematic way. Early on in the LINQ to XML documentation project, I spent four days writing a test harness (written in LINQ to XML, of course) that would automate my testing of snippets and examples. This allowed me to include as much code as possible. When I would receive a new version of the LINQ to XML assembly, I could set up my testing system, run the tests, and determine which snippets were broken in no time at all. In addition, during technical review, I received many suggestions for the snippets and examples. It would have been onerous to 1) copy the snippet back into Visual Studio, 2) fix the snippet, and 3) paste the snippet back into my documentation. Instead, in many cases, I would fix the snippet in place, right in the Word document. Then the testing harness would detect if I had made a mistake. Those four days were well spent.

This post details one approach to testing code in docs. Of course, there are many scenarios where this test harness would need to be modified significantly. If you are documenting a graphics library, you will need to validate that the graphical output is what you’d expect. If you are documenting a database, you will need to reset the state of your database after tests that modify the database.

I was working on a documentation project where it was obvious that the previous writer had edited the Word files without testing in any shape or form. ProgIDs were simply wrong. A property name was spelled correctly, but had the wrong case for the first letter of its name. These examples wouldn’t compile. I’ve also seen dead-tree books that had broken examples. Programmers live and die by good examples. Incorporate a system to ensure that your examples are not broken.

I never write a large book, manual, or document without first getting my snippet and example testing harness in place first.

Don’t Break the Example into Little Chunks

I’ve seen a fair amount of writing where the writer breaks up the code into little chunks, with explanatory text between the chunks. It often looks something like this:

The first thing you need to do is to include the appropriate using statements:

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

Next, declare your class and the Main method:

class Program

{

static void Main(string[] args)

{

Next, write the code to initialize the array and print it out:

int[] intArray = new[] { 1, 2, 3 };

foreach (var i in intArray)

Console.WriteLine(i);

Etc.

Developers read code for a living. Reading a program isn’t a problem. Why break it up? And worse, this makes it hard for the developer to build the example. Instead, include complete programs or complete snippets. If necessary, include comments in the relevant places. The following is a more appropriate form for the above code:

In the following example, you will see the necessary using statements, the declaration of the class and the Main method, and the code to initialize the array and print it out:

using System;

using System.Collections.Generic;

using System.Linq;

using System.Text;

class Program

{

static void Main(string[] args)

{

// initialize the array and print it out

int[] intArray = new[] { 1, 2, 3 };

foreach (var i in intArray)

Console.WriteLine(i);

}

Every piece of code in a document doesn’t need to be a complete, working example. The following is a complete, working snippet. It’s obvious that this code needs to be placed inside of a method.

// initialize the array and print it out

int[] intArray = new[] { 1, 2, 3 };

foreach (var i in intArray)

Console.WriteLine(i);

I have an exception for this rule – when explaining detailed semantics of a language, such as C# 3.0, for the examples that show more complicated language features, I will occasionally use the approach where I split the code into chunks. But only occasionally. When you do this, first show the listing for the complete example. Then, provide the listing for specific sections intermixed with explanations after listing the complete example.

But for programming interfaces, always include complete programs or snippets.

A book for beginning programmers might in a few places break up an example into little chunks. But even in that situation, I would focus more on presenting complete, working, commented examples.

Make Examples as Simple as Possible

Another way to say this – remove all of the noise from the example.

A few years ago, I was writing some samples to go into a book. One of the technical reviewers came back with the criticism: every example should be in a namespace, because all good code is in a namespace.

My response was that there are lots of things that good code should do and be, but unless those things are absolutely relevant to the example, leave them out. If you are writing an example that shows how to integrate several C# modules, then by all means, the classes should be in namespaces. However, if your code needs to show creation of an instance of a class or use of a method, putting the example in a namespace doesn’t help clarify the code.

I’ve seen other cases where examples were not as simple as possible. For example, I’ve seen some documentation on XPath where the examples use XSLT to print the results of XPath expressions. This wasn’t necessary. A simple C# or JavaScript example could have shown the results of the XPath expression without pulling in the complexities of XSLT. Certainly, there’s a time and place to show XPath’s use within XSLT, but for the sole purpose of demonstrating XPath, using XSLT isn’t appropriate, in my opinion.

I saw another case where the programmer writer had gone to lengths to write properties and the backing store for the properties, just to use those properties in a method call where an in-line string would have sufficed. This noise was unnecessary.

Follow Good Security Practice

As we know, developers will copy, paste, and modify examples and snippets. Code in documents WILL become part of a shipping software system somewhere. If you use bad security practice – embedding passwords in strings, using unsafe functions, etc., this code may introduce the bad security practice into the reader’s code.

This is an exception to making the example as simple as possible. Bad security practice has no place in an example.

I recommend reading the books on writing secure code by Michael Howard and David LeBlanc: Writing Secure Code, Second Edition, and Writing Secure Code for Windows Vista (Pro - Step By Step Developer).

Say It Simply

Cut words, especially adverbs and adjectives. Cut clutter. Write simply.

There’s a story about Franklin D. Roosevelt when he saw a government memo:

Such preparations shall be made as will completely obscure all Federal buildings and non-Federal buildings occupied by the Federal government during an air raid for any period of time from visibility by reason of internal or external illumination.

Roosevelt said, “Tell them that in buildings where they have to keep work going to put something across the windows.”

I took this example from one of my favorite books on non-fiction writing, On Writing Well, by William Zinsser. I recommend the book, particularly the first few chapters. It’s a well written book. J

One of the most memorable phrases from recent history is “Ask not what your country can do for you – ask what you can do for your country.” It’s a sentence that’s filled with single syllable, short words. There are no adverbs, and one possessive adjective. It’s an example of powerful, simple writing.

In the introduction to The Elements of Style, by William Strunk and E. B. White, Mr. White tells the story of Professor Strunk exhorting his students to “Omit needless words!” But when he had made such a strong statement that didn’t have any needless words, instead of interjecting needless words, he would repeat the message. He “leaned forward over his desk, grasped his coat lapels in his hands, and, in a husky, conspiratorial voice, said, ‘Rule Seventeen. Omit needless words! Omit needless words! Omit needless words!’”

Rewriting

The quality of my writing is directly proportional to the number of times that I rewrite. It’s always best if I let it ‘cook’ overnight between rewrites.

But I’m impatient – it certainly happens that I click the publish button, and then get that doh! feeling.

Craft Your Title for Search Engines

I’m pretty sure that search engines give extra weight to the title of the page (IANASEO). There are probably several search engine keywords that you’d want to find your story or blog post. Write your title using those words.

Summarize the Topic in the First Paragraph

This seems to be so obvious that it shouldn’t have to be stated, but I’ve seen too much writing that doesn’t do this.

The primary offense is that the topic gets into the technical weeds in the first paragraph. A bad first paragraph might be something like this:

The xyz class encompasses most of the functionality in the system, but the abc class augments the functionality in another way.

Instead:

This set of classes solves the problem of asynchronous communication between … This provides the benefit of reducing the number of servers in the zzz scenario.

If you don’t know how to articulate the core problem being solved, and the benefit, you should learn about these before starting to write. For marketing a product, marketing folks go through the exercise of writing the two sentence summary, the one minute pitch, and the five minute pitch. This is a good exercise for writers also. You may not need to agonize over them the way that marketing people do, but write them and post them on your wall.

A Few Miscellaneous Points

Here are a few other ‘rules’ that I follow for the most part. These are the miscellaneous rules that I consider to be the most important. I’ve seen good writing that breaks some of these rules, but I attempt to follow them.

Use the active voice. There is one exception in technical writing when writing about software systems with complicated abstractions. In some cases, the ‘doer’ is something that takes three sentences to define, and you don’t have a readily accessible noun for the abstraction. In those few cases, I’ll resort to passive voice.

Avoid the words ‘get’ and ‘got’. There are often more powerful verbs that you can use, and ‘get’ is so overused that personally, it jars my ears.

For example, instead of:

The abc class gets its GUID from the xyz class.

Say:

The abc class acquires its GUID from the xyz class.

Or:

The xyz class supplies the GUID to the abc class.

Don’t’ use the word ‘utilize’; use ‘use’ instead. Try this – in a situation where you would use the word utilize, substitute with the word ‘use’, and see if the meaning is the same, and is said more simply.

Don’t split infinitives. In the novel, The Caine Mutiny, one of the protagonists cynically tells another person that the best way to write a memo that that their captain will appreciate is to split some infinitives, because it gives a pretentious air to the document.

I don’t use 'performant'. It’s not a word. There are always ways to say the same thing using existing words and proper grammar, and sometimes with fewer syllables. Instead of, ‘That module is performant’, I prefer, ‘That module performs well’.

Like Jane Austin and the Wall Street Journal, I use the singular ‘they’ on occasion. It often yields sentences that are easier to read. This is one of those religious battles; I chose my side because I can use this construct to write in a way that is easier to read.

Use ‘which’ and ‘that’ correctly. ‘That’ precedes a dependant clause, and is not preceded by a comma. ‘Which’ precedes an independent clause, and is preceded by a comma.

This is the resistor that modifies the voltage of the fritzeryammer.

This is the main CPU, which provides the processing power of the system.

Paraphrased from Winston Churchill, a preposition is a fine thing to end a sentence (and a blog post) with.

Thoughts on Technical Writing for a Large Audience

EricWhite — Fri, 30 May 2008 18:40:00 GMT

[Blog Map]

One thing I love is good writing. I'm not making any claims about my own writing ability. (I tell my wife that I am the technical equivalent of a pulp fiction writer, more or less.) Technical writing is a craft, not an art. The other day, I was sitting in a meeting with a bunch of other Microsoft technical evangelists, and we were discussing the difference between "depth" content and "breadth" content. I think that we all intuitively know the difference - an in-depth book on building scalable SharePoint sites is "depth". A book that covers C# for a professional Java developer is "breadth". Here's my 2 cents on writing content that is applicable to a large audience. This post is pretty basic, but it might be useful to someone, so I'll post it.

The first thing to note is that breadth and depth are contextual. If we're putting together content on C#, depth and breadth will mean one thing. If we're putting together content on building scalable distributed web applications using C#, depth and breadth mean something altogether different. The same content in one context could be depth, and in the other context, breadth.

When I wrote the functional programming tutorial, my goal was "breadth". I wanted to target the tutorial so that it could reach the maximum number of C# readers, and specifically, those who are competent, but haven't yet "gotten it" about functional programming. I can recommend that tutorial for my nephew who is a junior in college, and I can recommend it for a friend in Colorado who has written literally a million lines of code, much of it in C++.

An extreme example of depth content is this KParts blog post. That blog post was primarily written for a handful of KDE experts who were also in the position of recommending a technical position to national standards bodies on the dispositions for Open XML. The page was visited by a fair number of people, but I'm pretty sure that there were only a handful of people who actually downloaded the code and built the example.

Compelling "breadth" content is written to appeal to the largest intersection of readers who are interested in a specific technology. However, it’s a bit of a balancing act. Cast too wide of a net, and you lose your audience. Cast too small of a net, and your content becomes "depth" content.

The "Sales" Process for a Reader:

Engaging a developer with content doesn't look like a "sales" activity, but in fact, that is what it is. There is an exchange - the developer spends his time with the expectation of receiving a positive ROI. This goes along with the theory that from a certain perspective, we're always doing sales. Even when writing nitty-gritty technical documentation, underlying the docs is an agenda: the writer wants the reader to understand the documentation, and be convinced that the technology is good, and worthy of continued use (or at least, the writer should want that).

Here is how I see the process when a a developer encounters some significant chunk of content - a book, an on-line tutorial, a Camtasia web cast, or a training course. In the beginning, the developer often hasn't made up their mind about whether to invest the time to read the content. There are several factors that go into this calculus. Probably the most important is "does the developer have a compelling, immediate need for the knowledge?" The most obvious example is that when a developer is assigned a project by his or her boss: "implement functionality X using technology Y". This is compelling motivation. Other factors - is it a hot technology? Will this technology be, in the developer's estimation, a key technology for the next three years? Will knowing about this technology make the developer more valuable, leading to a higher salary? Another important factor: has this content been recommended by others? If a technically competent colleague recommends a book to me, I'm much more likely to read it than if I randomly encounter the book while browsing through technical books at a bookstore.

Then, there is a point that I reach, shortly after starting the content, where I make the decision about whether to continue reading, or consuming the content. Bad writing can make me drop-kick a book quicker than just about anything else. I always figure that if the writing is bad, and the developer made the decision to write the content even though they can't write, then my trust in their technical competence is undermined.

Assuming too much knowledge, or worse, uneven assumptions about the knowledge of the reader are one of my prime indicators of bad writing.

More than 20 years ago, I needed to write a bunch of 'C' code to connect some computers and implement some functionality using RS232. In the process of researching my project, I hadn't found any books or magazine stories that detailed the particular information that I needed, so after completing my project, I wrote an article for the 'C User's Journal'. A colleague of mine was a well-known author of books on Unix. He graciously agreed to read and critique the first draft of my article. He pointed out that I had made a newbie writer mistake - the initial portion of my story was too basic - it was targeted at someone who wasn't familiar with all of the technical details of RS232. The second half of the article showed some sophisticated (at the time) techniques for error detection and correction - it would have been beyond the needs of someone who wasn't familiar with some of the basics of RS232. The solution was to simply discard the first half, and rework the second half to stand on its own. It's always painful to come to the realization that those words that I had labored over needed to be thrown out. It was one of those viscerally learned lessons that I try to not forget.

So this brings us to the idea of "breadth" content.

A breadth focus reaches as many readers as possible. A successful breadth story will have several orders of magnitude more readership than a depth story. And good breadth content "sells" the reader on continuing to read to the end of the story. This means:

Style: Breadth content is accessible / easy to read. Barrier to entry should be low. This is hard to quantify, but we all know what it is. Petzold's books are examples of breadth content. Academic papers are the antithesis of breadth content. I primarily attempt for a “programmer-to-programmer” style, talking to an imaginary professional programmer sitting across a table from me.
Content/Message: Content is properly targeted. Breadth content for a Sharepoint newbie is different from breadth content targeted at someone moving from SharePoint 12 to SharePoint 14. The emphasis needs to be on doing what they really want to be doing. The writer needs to focus on the 20% of effort that yields 80% of the required knowledge. Also, the content should be sufficient - not too much, and not too little. It shouldn't be daunting, but it should also good value for time if the developer spends his time looking at the content. I think that the size of consumable content is the length of the typical technical book - a dozen or twenty chapters, each of which takes an hour or so to consume.
Reader: Breadth content targets professional developers. In this context, very basic tutorials are "depth", not "breadth". They are written for a small sub-section of developers - those who are learning about programming. When I write, I develop a model of the targeted reader. What do they know? What do they not know? Also, there is a particular characteristic of professional developers that should never be forgotten when writing for them: Professional developers often already understand the underlying architecture - they just need a piece of working code that they can grab and modify for their needs. This is how pro developers work. We all intuitively know this; documentation usability testing confirms this. Characteristics are: snippets and code are complete, and can be run easily (you don't need to assemble code from here and there and elsewhere to create a working example). Taken to its logical extreme: click on a link at the top of the sample to see the code actually running. This is the direction that I want to see on-line books take.
Quality: Emphasis on writing quality should be high. The reader should enjoy reading / assimilating the content. The content should be "sticky". The reader should mark the site and come back for more. Telling stories causes stickiness. A good writer exposes his or her humanness and personality. The question that I ask myself after reading something I've written: after reading the first section, will the reader want to read more? The content should be entertaining, to the extent that such content can be.
Promotion: After completion of breadth content, it is necessary to publicize it.

The last point is particularly crucial. After the content is done, it is necessary to take action to drive traffic to the breadth content. Be persistent and take many different avenues. Measure the traffic and verify that the activities driving traffic are effective.

These characteristics are nothing more and nothing less than the characteristics for good writing everywhere and in any circumstance. The first three questions are the three questions that you always have to ask yourself before writing anything: Who is the reader? What is the message/content? What is the form/style?

This doesn't mean that it's easy. If good writing were easy, there would be more of it. Also, good writing is expensive. My general experience is that quality is directly related to the number of re-writes.

But good writing provides leverage. It lives on and develops a life of its own.