I'm the odd kind of developer that likes writing and explaining - emails, specs, you name it. I enjoy helping people understand things deeply. I hate ping-pong communications where groups go through 30 or 40 emails, phone calls and meetings because 25% of the group misunderstood the previous dashed-off email in which the writer only half-explained their position, or was in a hurry and miswrote a critical word or left out a negative or two.

This trait is great for documentation, but my emails are long, so people simply don't read them. A couple strategies I've used are formatting long emails as attached Word documents to encourage people to view them as documentation (works surprisingly well sometimes), or trying to use more bullet points instead of free paragraphs. These strategies increase readership, but the content is still long.

Of course I want to yell and scream that complex technical topics require a lot of exposition and clarification, but that doesn't help anyone. Obviously there are tradeoffs that can be made, but I have a hard time justifying making statements that aren't clear or that will result in a million questions, misunderstandings, or added "terms and conditions" later on.

How do you keep your communications short but complete?

  • 1
    Isn't this the problem Google Wave was supposed to solve? – Note to self - think of a name Oct 19 '10 at 23:57
  • @Note: Amongst many, yes. IMHO the main cause of its demise was that it was trying to be Everything, for Everyone. – Piskvor Mar 23 '11 at 15:06
  • 1
    This is not a programming specific problem – mattnz Jul 11 '14 at 4:13

Executive Summary:

Put the important facts at the top then expand below.


When I have a long technical email that I fear will lose half the audience, I make an effort to put a short, accurate "executive summary" at the top, and include the complete technical details below. Selective use of bold or underlining also helps.

  • Journalists practice this: the first paragraph of a story should give you the tl;dr version. Subsequent paragraphs then expand the story. – Frank Shearar Oct 20 '10 at 8:42
  • Just a point of clarification, do you actually label it as an executive summary? – Steven Evers Oct 21 '10 at 15:43
  • 2
    @SnOrfus, absolutely. It identifies it as a summary, let's the techies in the audience know that it is a compressed version of the whole story, and stokes the egos of the management types who wouldn't otherwise be bothered to read it. – AShelly Oct 21 '10 at 16:10
  • Very interesting. +1 – Steven Evers Oct 21 '10 at 19:10
  • 1
    The best reason for a one-line executive summary is that busy people use Blackberrys' to keep on top of email and the default display is only a few lines' worth. – JBRWilkinson Oct 21 '10 at 23:28

Focus on what you're trying to communicate. Does each word you've used help get your message across?

Try to avoid adjectives. Avoid ranting or over-explaining. Use the most concise phrase possible - don't try to sound impressive by using long words and complex phrases where a simpler option exists. Avoid wank words.

Read 'On Writing' by Stephen King.

  • Avoid adverbs even moreso than adjectives. They are almost always irrelevant. – Dan Rosenstark Dec 9 '10 at 0:15

I use fewer words, that seems to do the job quite well.

seriously, tho...

Try only explaining things that are pertinent, for example, "load a file" instead of going into detail about HOW you load the file and check for errors while doing it and etc. etc.

  • Wherever you can, link to an existing reference when a long explanation is needed, instead of including the entire explanation in the email.
  • Think about what the recipient wants to do with the information, and give them exactly enough to do that. Most non-hackers don't want to know any more than they need to get their task at hand done, and anyone who needs more will ask you.
  • As a general rule, when dealing with non-hackers, any email over one printed page in length (600 or so words) is too long. Either cut down on the verbiage, or beak most of it out to a link you can reference or a document you can attach. For example, 2,000 words of documentation should become a manual that you link to from or attach to the email. This makes it easier to keep the documentation updated and under revision control, too!

Read Strunk & White's The Elements Of Style

I quote, "Vigorous writing is concise. A sentence should contain no unnecessary words, a paragraph no unnecessary sentences, for the same reason that a drawing should have no unnecessary lines and a machine no unnecessary parts. This requires not that the writer make all his sentences short, or that he avoid all detail and treat his subjects only in outline, but that every word tell."

My favorite line, "Omit needless words."

alt text

  • The beautiful thing about this principle is that it applies to code as well. – Andy Lester Oct 21 '10 at 20:14

Write a succinct message and for things you think people may want details, provide hyper links to external Wiki pages from Wikipedia, eHow or even pages written by yourself.

Not the answer you're looking for? Browse other questions tagged or ask your own question.