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.

6 Answers
6

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 SheararOct 20 '10 at 8:42

Just a point of clarification, do you actually label it as an executive summary?
–
Steve EversOct 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.
–
AShellyOct 21 '10 at 16:10

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.

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!

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."