Superior writing skills are one of two things that separate novice developers from experts. This, as judged from experience, is self-evident to all people except bad developers. Here are the criteria that are generally most important:
* precision: This is perhaps most important. The ability to communicate tiny finite details that immediately reflects the product as a whole in a way that is universally clear to a wide audience in the same way is paramount.
* directness: Say what you mean. Don’t waste people’s time with distractions and pleasantries. Put the most important things first. If the audience wishes to read more they will.
* conciseness: There is an art to the careful description of technical details, behaviors, and examination of a subject that is both precise and still expressed in the fewest words/statements. An extended vocabulary is helpful.
* organization: Almost everything complex is open to more simplistic description as a subject of intrinsic relationships. The ability to perceive, understand, and convey those relationships is logic at its most base foundation but only when the those relationships are orderly and supported by evidence.
A common mistake is to be clever about organization, relationships, and their logic. Don’t do that. People do this as a weak form of manipulation, but strong communicators will tear it apart.
All of these points on writing are directly evident in well written code as well as formally expressed writings for general audiences.
* precision: This is perhaps most important. The ability to communicate tiny finite details that immediately reflects the product as a whole in a way that is universally clear to a wide audience in the same way is paramount.
* directness: Say what you mean. Don’t waste people’s time with distractions and pleasantries. Put the most important things first. If the audience wishes to read more they will.
* conciseness: There is an art to the careful description of technical details, behaviors, and examination of a subject that is both precise and still expressed in the fewest words/statements. An extended vocabulary is helpful.
* organization: Almost everything complex is open to more simplistic description as a subject of intrinsic relationships. The ability to perceive, understand, and convey those relationships is logic at its most base foundation but only when the those relationships are orderly and supported by evidence.
A common mistake is to be clever about organization, relationships, and their logic. Don’t do that. People do this as a weak form of manipulation, but strong communicators will tear it apart.
All of these points on writing are directly evident in well written code as well as formally expressed writings for general audiences.