Life Lesson: The More You Write, The Less They Read

Fall-2006

Since I realised this, life has become somewhat easier.  Being a Software Engineer means that I often have to communicate with people with non-software backgrounds, such as Clients, Management or Marketing.  A difficulty we have in communication, are the multi-letter acronyms (MLAs) and other jargon which is prevalent in software, and other technical fields I imagine.

When it comes to documentation, the initial reaction of a reader who doesn’t understand what you’ve written, is to claim that insufficient information was present (whether this is true or not).  The typical responce from the Engineer is to provide even more MLA and jargon loaded text.  Essentially providing a larger maze of documentation for the reader to get lost in, resulting in a request for more documentation, and the cycle goes on …

The solution to this conundrum is not more documentation, but more consice and succinct documentation.  Avoid MLAs and jargon where possible.  Where this is not possible do your best to explain it simply.  Know your audience, and speak in terms they can understand.  Do your best to keep it short and to the point.

Finally if all else fails.  Suggest a GIYF.