Does Bad Writing Reflect Poor Programming Skills?

Writing is a communication skill. And they say that communication skills and the other soft skills are what programmers need today. Effective developers don’t work alone. They work with others in a team. And a team member needs to communicate with the other team members to be effective.

[…]

Writing good prose, and good code, is more about style than about substance. Yes, the substance, the message is also important. But if your style is cluttered and unfocused, no one will grok your message. Your substance won’t matter.

Timothy King gives a deadly good example on communicating with code and comes up with three tips, I’m after:

  1. Understand the material before you write.
  2. Write as though your audience is a fourth grader.
  3. Think about how readers might misinterpret you.

These apply both to documentation, code and chat, as I might say. Even using them I use to restate things several times until my listener catches the idea, so I’d add this too

4. Say the same thing several times in different ways, so at least one of them would be successful.