Composing Semi-Formal Technical Email

Recently, I’ve put some effort into writing more effective technical email. Partly to be more effective in delivering the correct message, but largely to make sure the email gets read at all! Following are the formatting tips that I find most effective.

* Executive Summary - Explain high level intention of the email. What are you talking about? Why is it important? NOT technical - write this as though it's only for the high-level managers. This should be < 8 lines long (and you get bonus points for every line under that!).

* Bullet Point List - Issues that would guide the discussion if your email were to turn into a meeting. This is a great place for some ballpark estimates but don't get stuck in justifying your estimates at length. It’s ok if you get slightly technical, but try to avoid it - write this as though the CIO is no longer reading, but some management may still be with you. These should each be < 4 lines long and you’re trying to make the list short too. My magic number is 16 lines (not counting the white space): get much longer than that and they aren’t consistently read.

* More Details Section - Expand on the bullet points. Throw in your opinions and recommendations. Get technical if you need to. Keep your paragraphs pretty well defined. Each should be < 8 lines long and if there are going to be several paragraphs, the average should definitely be < 4 lines long. Don’t feel like you must talk about each bullet: some can be considered “covered” in your short list above.

You are writing under the assumption that the more you ramble on, the more you start to lose people. This goes hand-in-hand with the assumption that you are losing people in descending order of “title”. In your meeting the next day, you’re going to find that the client VP read the first paragraph, your manager read the first paragraph and the bullet points, and the only people that made it all the way to the end were the technical-developers: perfect.

Echo2 draft documentation available

I noticed today that Nextapp has recently added 'draft tutorial documentation', for Echo2, on their site. I haven't had a chance to look through all of it yet but I'm assuming that I can still probably get quite a bit out of it after being self-taught the basics.

If you're not at all familiar: Echo2 is a component based framework that generates html/js/etc via a 'Ajax Based Rendering Engine'. The goal being that you could develop a web application (utilizing Ajax) with very little knowledge of anything http-related. Of course, there are going to be some edge cases (i.e. creating custom components) that will likely require a very solid knowledge of these technologies, but you see the point...

I was trying to think of a good example application that I could try implementing with this and came across something in John Reynolds blog: An Echo1 implementation of a pretty straight forward hangman game.

My plan is to build something quite similar using Echo2 components.