Technical emails my best practice

When I was today preparing the presentation about UNIX basic I decide to put some UNIX philosophy slides on the beginning of it. Because I've read Raymond's Art of Unix Programing sometime ago I tought it would be perfect to use the some rules from him. So I go to the internet and find the list of rules from this great book. When I was reading them and figuring out which will be understandable for audience I said wait a moment some of those rules could be applied also in people relationships and mostly in written communication. 

The problem of today is that we are cooperating world wide in most of the companies nowadays and we use english to understand each others, well but not everybody is same level and after you send email, which is clear and perfectly understandable for you can make recipient angry, because of misunderstanding. Then you deal the call and say: "ohh sorry, it actually is about something else and it was not supposed to be offensive." In better case you just spend several more minutes to explain what was in email. But honestly it's waisting of time, because you could write your mail better.

Most of those problems of misunderstanding and explaining later on are cause by technician speaking to non-technician, in technical language and put things in complicated sentence. So we have here combination of different level of knowledge as well as different level of language skill. So here bellow find some Unix design rules which could be applied for mail communication:  

Rule of Modularity: Write simple parts connected by clean interfaces. 

Write simple statements, which are not to be misinterpreted and are connected in easy logical way. Rather use more simple sentences then one long.  

Rule of Clarity: Clarity is better than cleverness. 

Don't try to show your self as clever guy, because what is evident for you is not evident for others and they are not so much involved in topic as you. Expect your partner doesn't know the technical part so explain him like you would explain this to children.  

Rule of Transparency: Design for visibility to make inspection and debugging easier. 

If you are explaining some technical problem in the mail if you use simple statements instead of long sentences it's also more readable for other technicians. They can more easily follow the problem, because they doesn't need to search fact's hidden in the lot of nice 'colorfull' text.  

Rule of Robustness: Robustness is the child of transparency and simplicity.

If you will follow rules above you will have longer mail probably, but on the end more understandable and simple.

Rule of Repair: When you must fail, fail noisily and as soon as possible. 

This is not so much about communication, but more about behavior and it's not relevant to programming only but to any problem you may face. If you speak noisily about the problem and what can happened if it will not be solved people will listen more and it will be definitely easier to solve small problem and prevent bigger. In worst case you can then say: "Hey I've told you it's gonna be problem." So you at least are covered.  

Rule of Diversity: Distrust all claims for "one true way". 

Stay open to new ideas, even non-technical people could provide good technical solution or at least give you a hint or provide very good idea.

I've put link to this post to linkedin and ask the people there to put there tips about this topic. Here are the most interesting respons I've got:

I try and use pictures and non technical terms to explain technical problems to non technical people .The simple the better. Alot of people have a short attention span especially with the over abundance of information out there and if they don't understand what your explaining chances are they will lose interest.  

-- Chris Federico (http://www.linkedin.com/in/chrisfederico)  

In addition to screen-shots, I find that a numbered list of steps works wonders. If they run into difficulty, any follow-up communication can refer specifically to a step number. Just make sure that you keep each step simple and try it out yourself before sending.  

-- Tom Berryhill (http://www.linkedin.com/in/tomberryhill)  

It is a hard thing to do, but my best advice is to try to put yourself in the shoes of the person to whom you are writing. Try to imagine what it would be like to read the email if you knew nothing about it. Or imagine that the recipient is a 12-year old.  

And, keep the technical jargon, abbreviations, and acronyms out altogether.  

-- Josh Chernin (http://www.linkedin.com/in/jchernin)  

In tech support, I found it best to send screenshots or flash videos to explain a topic and train the customer on what needs to be done. 

A great free tool is Jing. Available at http://jingproject.com/  

-- Jared Farnum (http://www.linkedin.com/in/jaredfarnum)