The way you craft and structure technical announcements is key to capturing and retaining the attention of developers.
Developers are:
- natural problem-solvers
- with a keen ability to see through unclear (aka, BS) information
- many are non-native English speakers, which makes clear and structured communication even more critical.
In these series, you’ll learn 6 essential rules to help you craft clear technical announcements. This article is Part I. Part II is available here .
Part III is available via this link .
Rule 1: Use Active Voice
Using active voice in technical writing is crucial for clarity and engagement.
Active voice sentence follows a clear:
actor + active verb + target
structure, making your sentences straightforward and easy to understand. This contrasts with passive voice’s structure target + passive verb (form of to be + past participle verb) + actor, where the actor receives the verb and can often obscure who is doing what.
For instance, rather than writing:
"Bytecode was generated by compiler"(passive),
you should write
"Compiler generated bytecode"(active).
By consistently using active voice, you help your developers grasp your points more quickly and reduce the likelihood of misunderstandings, making your technical announcements more effective.
Rule 2: Use Strong And Precise Verbs
Strong verbs convey actions directly and powerfully, enhancing the clarity and impact of your communication.
For example, verbs like:
- “raise,”
- “generate,”
- “ensure,”
- “impact” drive your points home with strength and precision, making your statements more compelling and actionable. Conversely, weaker verbs such as:
- “is,”
- “are,”
- “happen,”
- “occur” can dilute the force of your statements, making them seem passive or vague. Instead of saying:
When a variable declaration doesn't have a datatype, a compiler error happens.(weak),
a stronger and more direct version would be:
A missing datatype on variable declaration triggers compiler errors.(strong).
By carefully selecting powerful verbs, you make your technical announcements more dynamic and clear, ensuring that your message not only reaches but also resonates with your audience.