When working with or mentoring other developers, one problem I’ve noticed is that many developers can’t write to save their life. This goes beyond “poorly documented” or whether grammar they get wrong (such as when writing in a second language). The main problem is one of organizing thoughts for a purpose and communicating them to an audience. This is something that everyone struggles with sometimes.
Most organizations, readers, and even managers don’t expect perfect grammar or prose from technical people. What they, or any reader, expect is that you get your point across clearly and in a manner they can understand. Learning to do this can often be the difference between being the leaders in a development organization and the folks that get tasked with all of the dreaded maintenance code.
If you break down the writing task as follows, you’ll be better at communicating—and convincing—through your writing.
Purpose
The first step in any writing, technical or otherwise, is to think about the purpose. Generally for developers, it is something like “explain what this piece of software does and why.” Sometimes it is “persuade someone that my approach is the best one.” Out of this usually comes a general outline of the idea you are pushing.
