I had the opportunity to attend an enlightening communications course over the past two days, delivered by John Sutherland. The intent of this blog post is to highlight some of the characteristics of effective written communication that I made notes of and share some of the experiments we, as Rangers, and I, as an individual, are planning for the next few months.
Effective Engineering Writing
The course highlighted the following principles to be considered when creating a piece of information, whereby the italic text are my personal notes I made during the course:
- Direct … start with the eye-of-the-storm, especially when information will be scanned/skimmed on reduced surface area devices, i.e. phones.
- Concise … cut the fluff and include only the important information.
- Precise … include precise information within context, for example submit on 13 August 2013, not some time in August.
- Complete… include detailed information within context, for example when reporting an error include details, repro-steps and relevant dumps.
- Easily understood … avoid slang, acronyms and complex language where possible.
Obviously the course delved into many other strategies and concepts, which are best covered in a separate post. The reason I decided to create this post is to highlight a few of the engineering changes we have introduced and my personal objectives that are in support of the above principles.
What are we planning as Visual Studio ALM Rangers?
Recent guidance projects have shown a huge improvement in quality and readability, which is primarily thanks to the technical reviews done by one of our Rangers, Patricia (Technical Editor).
The new wave of Ranger solutions are enjoying:
- Revised templates, introducing a professional and most importantly a consistent look&feel.
- Content scripting by the project leads,to define the skeleton of the guidance and/or out-of-band solution. Expectations are clearer and the team can focus on adding the content.
- Technical reviews, ensuring that the principles of effective engineering writing are applied and that the content is correct and compliant.
- New infrastructure, which is aimed at PULL, rather than PUSH information strategies. This allows Rangers to define what is important to them and how they want to be alerted of changes. Some of the immediate impact on all Visual Studio ALM Rangers include:
- Meeting invites are sent to context specific audience, not to all Rangers, by default.
If a Ranger wants to be notified of all meetings, an alert must be defined in the Ranger Meetings list on the Rangers portal.
- Project specific collaboration has moved away from email to Discussion Forums on the Rangers portal.
- All email, which has been substantially reduced, is based on Controlled Vocab which allows Rangers to defined complex email rules.
|We want to reduce and avoid the information, especially email, wave… || |
Ranger must be able to define what and when to receive information …
| || |
What am I planning as an individual?
I have set myself two personal goals:
- Crisp, terse and quality documentation and email communication
- revise, revise and revise again
- structure content around a maximum of seven points and avoid scrolling emails
- Reduce volume of email communication.
I am aiming for an initial daily cap of 13 new email threads per day, excluding REplies and ForWards. Note that 13 is my lucky number, not a scientifically based number and merely a kick-start limit.
For example, every time I start a new email, I am now confronted with the following hints:
- Context first?
- Instructions included?
- Action items / owners clear?
- Note: Direct|Concise|Precise|Complete|Easily Understood| No Assumptions
- Question: im, forum or phone possible instead?
After I have clicked send, I have a further 30 minutes to think about it, stop and edit the email. After the 30minutes, the email leaves my outbox and in many cases the typos and other ineffective communication gremlins are noticed … but, hopefully the regret of clicking send and the resultant waves will be drastically reduced
Improvement is based on candid feedback … so please add your candid comments to this thread or contact me direct here.