13

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?

Improve this question
3
  • 1
    Isn't this the problem Google Wave was supposed to solve?
    – Note to self - think of a name
    Commented Oct 19, 2010 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 left the building
    Commented Mar 23, 2011 at 15:06
  • 1
    This is not a programming specific problem
    – mattnz
    Commented Jul 11, 2014 at 4:13

6 Answers 6

Reset to default
10

Executive Summary:

Put the important facts at the top then expand below.

Details:

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.

Improve this answer
5
  • Journalists practice this: the first paragraph of a story should give you the tl;dr version. Subsequent paragraphs then expand the story.
    – Frank Shearar
    Commented Oct 20, 2010 at 8:42
  • Just a point of clarification, do you actually label it as an executive summary?
    – Steven Evers
    Commented Oct 21, 2010 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
    Commented Oct 21, 2010 at 16:10
  • Very interesting. +1
    – Steven Evers
    Commented Oct 21, 2010 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
    Commented Oct 21, 2010 at 23:28
2

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.

Improve this answer
1
  • Avoid adverbs even moreso than adjectives. They are almost always irrelevant.
    – Dan Rosenstark
    Commented Dec 9, 2010 at 0:15
1

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.

Improve this answer
1
  • 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!
Improve this answer
1

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

Improve this answer
1
  • The beautiful thing about this principle is that it applies to code as well.
    – Andy Lester
    Commented Oct 21, 2010 at 20:14
0

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.

Improve this answer

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