Thoughts on Technical Writing for a Large Audience
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.
This blog is inactive.
New blog: EricWhite.com/blog
Blog TOCThe 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.