Gregor's Ramblings

Writing for Busy People

SEP 21, 2014

Gregor Hohpe




Quality vs. Impact

Writing is a tough business because writing takes so much more effort than reading, but the written word has distinct advantages over the spoken word:

  1. it scales: you can address a large audience without gathering them all in one room (podcasts admittedly can also accomplish that)
  2. it's fast: people read 2-3 times faster than they can listen
  3. it can be easily searched or versioned.

Consequently, writing pays off once you have a large (or important) enough audience. The catch is that while you can to some extent force people to (at least pretend to) listen to you, it's much harder to force anyone to read your stuff. I always remind writers that "the reader is by no means required to turn the page. He or she decides based on what they read so far." Hey, I am writing this only in the hope that people will read it because they find it useful. Assuming the topic and focus of the paper are correct, i.e. the readership has a fundamental interest in reading the paper, I have repeatedly observed a classic non-linear relationship between the quality of writing / editing and the actual readership, which is a good proxy metric for the impact, or the "pay-off" of writing a technical paper. If the paper does not meet a minimum quality bar, e.g. it is verbose, poorly structured, full of typos, or displayed in some ridiculous, difficult to read font, people won't read it at all, meaning impact is near zero. I call this the "trash bin" zone to make the outcome blatantly obvious. You may euphemize it to "shelfware zone", but the impact remains the same: zero. Once the paper reaches a certain quality threshold, people will in fact read at least part of the paper and impact starts building. As so often, additional quality initially brings rapid improvement, but then quickly tapers off as it approaches the infamous "gold plating" zone.

Value curve of writing quality

The biggest debate I tend have with my colleagues is where the sweet spot or "tipping point" is. It will certainly depend on what you are writing and for whom, but in corporate communications I posit that it is further to the right than most authors believe. Key influencers are very busy people and tend to shy away from anything that is more than 5 pages long, unless it is from a high-paid consultancy, in which case they make someone else read it. For this impatient readership, clarity of wording and brevity are not nice-to-haves: their lack will quickly put your paper quite literally into the "trash bin" zone. Unsubstantiated claims will do the same: I recently saw an internal presentation where the first slide stated "only technology ABCD has proven to be a viable solution". My immediate response: "great, show me the proof!" Sadly, no proof existed due to lack of time and funding. These are not wording issues, but fatal flaws. I no longer want to see page 2 if I cannot trust page 1.

"In the hand" - First Impressions Count

When Bobby and I wrote "Enterprise Integration Patterns", the publisher told us about the importance of the "in the hand" moment, which occurs just when a potential buyer picks the book from the shelf and gives a quick glimpse to front and back cover, maybe the table of contents, or leaves through the book (back in 2003 people still bought books in physical book stores). The reader makes the purchasing decision at this moment, not when he or she stumbles on your ingenious conclusion on page 326. This is one (but not the only) reason why we included a lot of graphics in our book. About 80% of all facing pages contain a piece of graphic: an icon (aka "Gregorgram"), a pattern sketch, a screen shot, or even a UML diagram. This sends an important message to the potential reader that the book is not academic, but pragmatic and approachable.

The same is true for technical papers to be read not by academics, but by a corporate audience. Use a clean layout, insert a handful of expressive diagrams, and, above all, keep it short! We limit our internal papers to 5 pages (at 11pt sans serif font this equates to 2000-2500 words, about the length of this rambling), with the inevitable occasional exception.

To assess what a short paper will "feel" like to the reader without wasting printer paper, I zoom out my wysiwyg editor far enough that all pages appear on the screen. I can't read the text anymore, but can see the headings, diagrams, and overall flow, e.g. the length of paragraphs and sections. This is exactly what a reader will see when flipping through your document and deciding whether to start reading. If they see and endless parade of bullet points, bulky paragraphs or a giant mess, the paper will leave "the hand" quite quickly as gravity teleports it into the trash bin.

A technical paper zoomed out

This example paper has a lot of diagrams, which is good. However, their visual style is somewhat inconsistent. Also, some diagrams are wrapped by text while others are isolated. All in all the paper looks interesting, but probably a little too "busy".

A good paper is like "Shrek"

Most animated movies have to entertain multiple audiences: the kids who love the characters and humor plus the adults who had to shell out thirty bucks to take the family to the movies. Great animated movies like "Shrek" manage to address both audiences without boring the other. They will laugh at different scenes without being distracted by each other. Many technical paper also have to address a broad and diverse audience: some readers will look for technical detail while others are more interested in key decisions and recommendations. While challenging, a few mechanisms can help make everyone happy:

  • An executive summary prefaces the actual paper with the highlights and key decisions. For short papers I avoid summaries as I fear they entice readers to not read the rest. If everything important can fit into the summary, then why write a whole paper?
  • Story-telling headings are a great way to engage readers with very little time while still taking them through the whole paper. Imagine your readers only read the headings. Will they get the gist of the paper? This implies that headings like "introduction" or "conclusion" have no place in a short paper. Instead, simply state what the context or conclusion are.
  • Diagrams can provide a visual anchor for important parts of the paper. Readers who flip through may pause at a diagram, so it's good to position them strategically to guide the reader to critical sections. Diagrams also help readers who better reason visually than from words alone.
  • Callouts, i.e. short sections that are offset in a different font or color, indicate to the reader that additional detail is provided, but that it can be safely skipped without losing the thread of thought. Bobby and I used them in EIP when we could not agree whether to include or remove a section which provided "color commentary".

Making it easy for the Reader

After a good first impression, your readers will start reading your paper. Because trying to condense all good advice on technical writing into a blog entry would be preposterous, I like to refer my colleagues, who are mostly non-native speakers, to the book Technical Writing and Professional Communication for Non-Native Speakers (it appears out of print, but you can fetch a used copy for a few Dollars - I only have the second edition from 1991, so I can't comment on how similar it is to the first edition). It covers a lot of ground from the very basics, but I like the sections on parallelism and paragraph structure best because the fast reader benefits significantly from these simple tricks.

Parallelism in lists demands that all list entries follow a similar grammatical structure, e.g. all start with a verb or an adjective. A counter example would be:

System A is preferred because:

  • It is faster
  • Cost is also important
  • Flexibility
  • Stable
  • Don't forget to look at long-term evolution

You are simply using too many of your reader's brain cells just to parse the text instead of focusing on your message. Parallelism is not only useful in lists but also in sentences, e.g. when drawing analogies or contrasting. Technical Writing and Professional Communication for Non-Native Speakers includes many good examples of this.

Paragraphs should focus on a single topic and introduce that topic right at the beginning, like this very paragraph: readers can glean that this paragraph is about paragraphs even if they only read the first word. They can also rest assured that I don't start talking about lists or grammar halfway through, so if they feel they already know how to write a good paragraph, they can safely skip this one. This also implies that "It is further important to note that..." makes for a very poor paragraph opening.

How do you spell "hierarchy"?

For solid document structure I tend to point colleagues to The Pyramid Principle, even though I jest that the author must have been unsure how to spell "hierarchy" and safely opted for "pyramid" instead -- to me the logic inside the books is clearly about hierarchy of content. Pyramids stand in Egypt. This book tackles another enormous challenge in technical writing: your subject is very unlikely to be single-dimensional, but your text has to be 100% linear: one word after the other.

While somewhat over-hyped and over-priced, I do appreciate the book's sections on order. The author highlights that every list or grouping should have an order, which is either by time (chronological), structure (relationships), or ranking (importance). "How is this ordered?" has become a standard question when I review documents including a list or grouping.

Another pet peeve of mine is the usage of the word "this" as a stand-alone reference. As programmers we understand the dangers of dangling pointers and NPE's, but many seem not to apply the same rigor to writing. Too many sentences simply state that "this is a problem" without being clear what "this" actually refers to.

In der Kuerze liegt die Wuerze

In technical writing, your readers are not out to appreciate your literary creativity, but to understand what you are saying. This implies that less is more when it comes to word count. While Walker Royce's book Eureka!: Discover and Enjoy the Hidden Power of the English Language spends a good part of the book musing about English words, the advice on brevity and editing is sound and the citation from Zinsser on the usage of "I might add," "It should be pointed out," and "It is interesting to note." fitting: If you might add, add it. If it should be pointed out, point it out. If it is interesting to note, make it interesting. The book gives many concrete suggestions on how to replace long-winded expressions with single words.

In our team's internal editing cycles we routinely cut word count by 20-30% despite including additional material or previously missing detail. To the first-time author this may be shocking, but Saint-Exupéry's adage that "perfection is achieved not when there is nothing more to add, but when nothing is left to take away" is especially true for technical papers. When this type of cruel editing was first bestowed upon me by a professional copy editor I felt that the document no longer sounded "like me". Over the years I have come to appreciate that being crisp and accurate is a great way to have a document sound like me.

Writer's workshop

The most effective vehicle for improving technical papers is to hold a writer's workshop, see this short description or this long description for more detail. Writer's workshops have people read and discuss the paper while allowing the author to listen, but not intervene. This simulates what happens with a paper in real life. Too often I have to remind authors that we cannot distribute them personally with every copy of their paper so that they can explain to the reader what was really meant. Because writer's workshops are time-intensive we tend to restrict them to papers that have gone through an initial review for comprehensibility, but are expected to have a large and diverse audience, justifying the extra effort.

Producing Paper

Producing high-quality position papers can lead to an unexpected amount of organizational head-wind. The word "perfection" quickly comes up with an invariably negative connotation. Other teams claim that their "agility" spares them from any need to produce documentation, notwithstanding the fact that those teams have no running code to show either. Agile software development places the emphasis on producing working code that is worth reading, but multi-year IT strategy plans are unlikely to manifest themselves in code alone. This is where a document that is worth reading will provide the most value. Alas, such documents seem to be even more difficult to find than good code.


I would like to thank Olaf Zimmermann for the fruitful discussion at ECSA 2014 that inspired me to write down my thoughts on writing for busy people.


Follow:       Subscribe  SUBSCRIBE TO FEED

