Writing for Professional Developers
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
This blog is inactive.
New blog: EricWhite.com/blogBlog TOCWhat 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.
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.
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.