Being Excellent at Communicating Technical Work

When you make changes to a product, there are many people who will feel the effects.

If you’re a developer, designer, or project manager, it is your job to communicate these changes.

Communication can be hard, especially when you need to speak to people with different levels of understanding and empathy.

Today we’re going to share some of the types of people you should be communicating with and how to pitch your message best for them.

What changes should we communicate

It is hard to give exact rules to follow for what should be communicated.

Here are some things that should not be freely shared:

Specific security issues – talking at a high level can be fine, but giving too much away could expose other issues for attackers to try

Things that fall under “general maintenance” – Smaller updates to third party code or security patches rarely need to be specifically talked about

These are the main things we’ve found most pertinent to share:

Bug fixes — something that wasn’t working properly but now is

New features — something that didn’t exist before but now does

Change in functionality — New ways of doing old things

Who we communicate with

As developers, we have a habit of under-communicating, or at least only communicating with other developers.

Work that hasn’t been communicated may as well have not happened since people don’t know about it.

Here are all the key people who are affected by your product updates and need to be notified:

The customer

Sales and Marketing

Support

Affiliates

Technical folk

Depending on your company setup, you may not be the person who informs these people directly, but you do need a system in place to make sure they are kept up-to-date.

The customer

The customer, or the end user, is the person who will actually be using the product you’ve just improved. There are a couple reasons to inform customers of updates.

If they don’t know about the change, then the work may as well not have been completed. Customers like to see bugs getting fixed, plus if they have a bug they keep running into, they are waiting to see it fixed. Customers like to see the products they pay for being actively developed. If apps stop getting updates, that’s usually a sign the product is dead and they need to find a new one.

In most companies, the person who made changes isn’t the person who would be speaking directly to the end user, but if you keep the user top of mind when writing updates, you will avoid overly technical language.

The end user will care about all three of the things that need to be communicated:

Bug fixes – will enable them to complete a task they couldn’t finish before

New features – will allow them to achieve more with your product, or do a thing they’ve been wanting to do but couldn’t

New ways of doing things – changes to how things are done can be very unsettling for a user, especially if they’ve been doing the same thing for months or years

Example communication

A bug fix might be communicated in an email:

Thanks to everyone who pointed out the issue with saving a new avatar, we’ve just fixed this. Check out your profile page and let us know if you have any problems by emailing help@company.com.

Why this works:

Thanking people for their feedback is essential

It doesn’t get into the technical details of what was fixed, if people are interested they can check the detailed release notes, most people just want to know about the new thing that helps them

It explains how people can view the fixed issue

There are clear next steps if something is still broken

A new feature could be communicated with this email:

New for v.3.5, You can now comment on new items! Thanks to everyone who requested this feature, you asked, we built it! Test it out today by going to any item, and you will see a comments area. If you get stuck or have any other awesome ideas for us, please email help@company.com

You will notice this is very similar to how to communicate a bug fix. This is because fixing a bug is essentially enabling a feature. In both cases, something that couldn’t be done now can.

Finally, communicating a change in functionality:

We’ve made some changes to how you link your social media profile. This used to be in Profiles > My Accounts, it is now in Profiles > Social Media > Accounts. We think this will make things more clear for new people using this feature for the first time.

Why this works:

It doesn’t claim to be an improvement, we aren’t saying the old way was bad, just different.

We clearly state how the old way worked and how the new approach works for comparison.

There was a reason given for the change.

Sales and Marketing

In some companies, Sales and Marketing are combined. While Marketing focuses on the messaging of one to many, such as sending an email blast to all the users, Sales focuses on one to one, a salesperson might send personal emails directly to interested prospects to engage them in a direct conversation.

Obviously, companies require sales to grow the customer base and make money. Having a strong sales team is one a great way to ensure that.

Marketing are the folks who work out how to take the changes you’ve made and communicate that to customers in a way the can understand and in a way that speaks to them.

This is an incredibly hard job, and the more information we can give them, the better. After all, they need to understand the changes made so that can correctly communicate them to the customers.

Out of the three things to be communicated, sales and marketing will care most about:

New features – So they can work out how to communicate the new feature widely.

New ways of doing things – So they can update older communications or revisit how they’ve sold something in the past.

Example communication to Sales and Marketing

A new feature might get communicated like this:

Just to let you know, PRODUCT now lets you comment on items, anyone with an account can do this. We’re pretty sure this is “feature complete”, we won’t be adding anything to this.

Why this works:

It explains the types of users that can do the action

It sets expectations about the future longevity of this feature

An example of a change in functionality message:

We’ve made some changes to how you link your social media profile. This used to be in Profiles > My Accounts, it is now in Profiles > Social Media > Accounts. We think this will make onboarding more comfortable for new users and improve our metrics around social media linking.

This is very similar to the communication we suggested for the end user. This will be a theme throughout all the user groups, we often just need to make small changes.

For this example, we’ve also explained the business reason behind the change as that is important to the audience of sales and marketing.

Affiliates

Affiliates are midway between your Sales team and your users. They want to earn your company money by making sales on your behalf, but they don’t have access to the internal training or jargon that you might have. For this reason, you can’t just send them the same information you would send Sales.

Like Sales, Affiliates are going to care most about new features.

Interested in becoming a Smile or TextExpander affiliate? Find out more.

Example communication

A new feature might get communicated like this:

Exciting times ahead! We just launched a feature that lets users comment on items, anyone with an account can do this.

This is a bit more like a sales pitch because we want the Affiliate to take action and use this information to drive sales. We also removed stuff only relevant to internal folk, such as the product being feature complete.

Support

Support folk are always the ones fielding customer questions and feedback when changes appear in a product. If they have the right information about modifications on hand, they will be able to respond to the increase in questions quickly.

Support will care about all three of the types of things product changes:

Fixed bugs – so they can get back to users and close off old tickets.

New features – so they know what new categories of questions might come in.

Changes in functionality – so they can pre-empt confused users unsure about how to navigate the updated features.

Example communication

A bug fix might be communicated like this:

There was an issue with saving a new avatar, we’ve just fixed this [BUGNUMBER-123]. Users can upload their avatar successfully from their profile page now.

Unlike the communication we suggest for customers this communication has a more matter of fact tone, it is more of a statement that a Support person can use when crafting their emails back to the people who reported the issue.

A new feature could be communicated like this:

We just made a feature that lets users comment on items, anyone with an account should be able to do this. We’re pretty sure this is “feature complete”, we won’t be adding anything to this.

A logged in user viewing an item will be able to type plain text into the comments area and hit “Add Comment. If they are replying to someone, the text will say “Add Reply”.

We don’t support linking, formatting, or adding images to comments.

When communicating with Support, it is essential to mention the things that can’t be done that some people might expect. This saves a lot of back and forth, trying to work out if something is a feature working as intended, or a bug.

Finally, communicating a change in functionality:

We’ve made some changes to how you link your social media profile. This used to be in Profiles > My Accounts, it is now in Profiles > Social Media > Accounts. We think this will make things more clear for new people using this feature for the first time.

This is close to how we communicated the change to a user.

Technical folk

Development teams that communicate well internally are more productive and happier. This is why it is crucial to communicate the work you’ve done to the rest of the Technical team.

Some of this communication will happen during code review or pairing, but not every developer will be involved in that, so a timely note about completed work will keep everyone in the loop.

Out of the three things we’ve suggested you communicate, technical people will care most about:

Bug fixes — there was something wrong in code that needed to be fixed.

New features — there have been new parts added to the codebase, that could increase complexity.

Example communication

These communications will be a lot more technical and should use the correct terminology.

A bug fix could be communicated like:

There was an issue with the gem we used to upload to S3, it was occasionally returning a 500 even though the upload completed successfully. It is a known bug (link to the bug) but doesn’t look like it is getting fixed anytime soon.

We’ve swapped out the old gem for a new gem (link to gem documentation). It has all the features of the old gem but doesn’t appear to have this issue.

This was affecting users uploading their avatar.

Why this works:

It links to documentation for people who want to find out more.

It gives a reason for changing code.

It explains the user need.

A new feature could be communicated like this:

We’ve just launched a way to comment on items. To do this, we created a Comment model which belongs to a User and an Item.

You can find the relevant tests here (link to tests).

In this short note we’ve covered:

The feature that has been made at a high level.

A mention that there is a new entity in the system.

A link to the relevant tests, where people can learn more about the functionality.

Who have we missed

Who are the groups of people you keep in the loop about product changes you’ve made? Let us know on @TextExpander and on Facebook.