Crafting Effective Announcements

In this world of omnipresent change, effective communication is key to survival. Information that will impact others must be shared, and how that sharing is done will be the difference between success and failure. Will recipients of your message be confused, or will the message be clear? Will others take the right action, or will the messaging mislead them causing more problems? Will you waste others’ time? Will your message result in a tidal wave of unnecessary meetings and video conferences?

The 5 W’s

To prevent the relentless tide of change from drowning you and your organization, make sure your announcement clearly, concisely, precisely, and accurately answers the 5 w’s:

• Who?
  Indicate who is impacted ensuring that the right people pay attention and others don’t waste their time.
• What?
  Clarity on what is changing allows recipients to formulate an effective response to the change.
• When?
  Specify when the change will be made to let recipients schedule around it. If a change already happened versus if a change will happen in a year require very different responses.
• Where?
  Tell recipients how to get more information. For example, include a link to more detailed information and contact information for who to contact with questions.
• Why?
  Why should the recipient care? What is the significance to them?

Do your best to ensure that the message can be understandable and is actionable by all recipients.

Example 1: Early Release at School

The need to effectively message doesn’t just happen in the workplace.

Way back when I was in Kindergarten, school was dismissed extra early on the day before Thanksgiving. However, the messaging from the school wasn’t clear to my mother (who would be horrified to learn that I’m sharing this story) resulting in me spending a lot more time with the school staff that afternoon than I would have liked.

Having learned a lesson in how ineffective communication can be problematic, I do my best to avoid having the next generation learn that same lesson the hard way again.

Here’s a simple example that happened at my home recently using text messaging:

Our daughter has a half day of school today. She’ll be home early at 11:50 instead of the usual 3:00. Can you please pick her up? Let me know if there’s anything I can do to help.

Text message from me to my better half

Note how the message addresses the 5 W’s. Effective communication eliminated the risk, resulting in my daughter spending the afternoon happily at home.

Example 2: The Log4j Core Vulnerabilities

Here’s an announcement I ran across:

There is a critical security issue in log4j. Everyone must upgrade log4j immediately!

That announcement has a lot of problems. It does answer “what,” “who,” and “when” but not very clearly. This message would result in a lot of questions, wasted time, confusion, and panic.

All projects using log4j < 2.15.0 must upgrade log4j to 2.15.0. By the end of today, all impacted projects must submit plans which include having the upgrade complete by December 23. For more information, see CVE-2021-44228.

Better, but still not great. Who submits the plan, how do they submit it? How does a project know it is impacted? Who can people contact to learn more?

All projects using log4j-core < 2.15.0 must upgrade to 2.15.0 or later due to a very high severity vulnerability allowing full remote take-over of impacted systems.

Projects can determine if they’re impacted by checking for a dependency on logj4-core with a version less than 2.17.0. Note that projects that include log4j-api only do need to do anything – they are not impacted. Only projects using log4j-core are impacted.

For projects using Gradle, run: ./gradlew dependencies then search the output for log4j-core.

For projects using Maven, run: mvn dependency:list then search the output for log4j-core.

Projects using other build systems should consult their build system’s documentation.

For project that are impacted, see Log4J2 Vulnerability and Spring Boot for information on how to perform the upgrade.

By 5pm ET today, the project manager for each impacted project must submit a plan which includes having the upgrade complete by December 23 at <URL>.

For more information, see CVE-2021-44228. For questions, comments, and support, reach out to developer services at <URL>.

This iteration is much better.

• The “who” is clear, starting with a summary (“All projects using log4j-core < 2.15.0”) which allows non-developers to ignore the message, then proceeding to detailed steps allowing projects that don’t use log4j to realize they are also not impacted.
• The “what” gives a link to a document that explains how to respond.
• The “when” gives a specific point in time with clear instructions for who needs to perform what actions.
• The “where” provides additional information to learn more and how to ask questions.

A Tale of Headaches and Risks Introduced by Ineffective Communication

Imagine a developer receiving an announcement very similar to the second log4j example above:

All projects using log4j < 2.15.0 must upgrade log4j to 2.15.0. By the end of today, all impacted projects must submit plans which include having the upgrade complete by December 23. For more information, see CVE-2021-44228.

Being excited by the urgency expressed in the announcement, they wanted to immediately address this problem. Security is important after all – every second counts!

They searched the web and found that adding a block like this to their Gradle build.gradle would upgrade them to log4j 2.15.0:

implementation group: 'org.apache.logging.log4j', name: 'log4j-api', version: '2.15.0'
implementation group: 'org.apache.logging.log4j', name: 'log4j-to-slf4j', version: '2.15.0'
implementation group: 'org.apache.logging.log4j', name: 'log4j-core', version: '2.15.0'

The project team released the updated project to production.

Problem solved, right? Enter more log4j vulnerabilities…

Within days, log4j 2.16.0 then 2.17.0 and finally 2.17.1 are released fixing more vulnerabilities. As each new version is released, the developer modifies build.gradle to use it, then a release to production is made.

However, none of that was necessary – the developer had actually introduced vulnerabilities and caused work for themself, their team, and added risk to the organization as a whole.

This project didn’t originally use log4j-core, which was the only impacted logj4 component. The project was not vulnerable until the developer added the dependency on logj4-core. In other words, after adding the dependency on logj4-core 2.15.0, the project became vulnerable to CVE-2021-45046.

A better announcement message would have saved time and reduced risk. Consider this improved announcement:

All projects using log4j-core < 2.15.0 must upgrade to 2.15.0 or later due to a very high severity vulnerability allowing full remote take-over of impacted systems.

Projects can determine if they’re impacted by checking for a dependency on logj4-core with a version less than 2.17.0. Note that projects that include log4j-api only do need to do anything – they are not impacted. Only projects using log4j-core are impacted.

For projects using Gradle, run: ./gradlew dependencies then search the output for log4j-core.

For projects using Maven, run: mvn dependency:list then search the output for log4j-core.

Projects using other build systems should consult their build system’s documentation.

For project that are impacted, see Log4J2 Vulnerability and Spring Boot for information on how to perform the upgrade.

By 5pm ET today, the project manager for each impacted project must submit a plan which includes having the upgrade complete by December 23 at <URL>.

For more information, see CVE-2021-44228. For questions, comments, and support, reach out to developer services at <URL>.

Following the instructions included in this announcement, the developer would have quickly realized that their project was not impacted because it didn’t depend upon log4j-core, and therefore would have never introduced the dependency on it along, sparing the project and the organization exposure to the other vulnerabilities.

Wrapping It Up

Effective communication is important in all aspects of life, personal and professional. Keep in mind that communication is done between people. By humanizing the recipients of your message, you can improve your empathy and respect for them, reminding you to take the extra time to think about the messages you produce.

Good communication is the bridge between confusion and clarity.

Nat Turner

Crafting Effective Announcements by Craig Andrews is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.