Friday, February 14, 2014

On the Subtle Art of Technical Communications

What I have been doing for the last decade or so can be summed up in one word: Innovation. The main product of innovation is information and we communicate information via documents. I wanted to share some lessons I learned about creating documents that, I think, some of you might want to adopt or, at least, consider.
  1. Remember the three main goals of technical writing – a good document balances all 3:
    • Educate – make people understand more than they did before reading your stuff
    • Inform – make sure people know more than they did before reading your stuff
    • Entertain – make sure no one ever feels bored while reading/listening to you. This last one is an art in its own right, and requires a combination of practice and talent. Intrigue can often serve as a good substitute: make a claim/statement/promise that will grab readers’ attention early on and then weave your story to substantiate it.
  2. There is a fourth ever-present the implicit goal: Influence. If you write or say something, there has to be a reason for it. In many cases it is to make or change your readers’ minds and everything you do should support this purpose. Documents should be carefully architected, designed and built – just like software!
  3. There is always should be a coherent story – make sure you construct your narrative before you start your work.
  4. People love stories and anecdotes: weave them into your story line to support each part of your narrative. A colleague of mine once tried to understand why I deliver a presentation that grips, engages and influences the audience every time and he never gets the same result when telling the same story using the same deck. He used a scientific approach and gathered data over a number of my presentations and noticed that I have a library of about 35 different stories, anecdotes and vignettes and each time I deliver a presentation I use a different subset of about 25 – roughly one per slide. He tried to imitate that approach and got much better traction with the audience.
  5. Text is boring and tedious – use pictures. If you don't have a relevant technical picture, put a humorous one related to the key concept of the slide:
    • Talking about the dangers of exclusively relying on SSL for Web Service Security – use an image of leaky pipes:
    • Covering SLA Enforcement – show a speed trap:
    • Describing ways to interconnect virtual private clouds through a IPSec bridge – awe the reader with an image of colliding galaxies exchanging a stream of stars:
Couple of interesting posts by Nancy Duarte on the subject:

No comments:

Post a Comment