Communicating technical concepts to non-technical people
Keep the technical terms and make them accessible
Writing in technical terms to non-technical people is an important skill to practice. I believe it's better for everyone if a software developer uses proper technical terms when communicating with non-technical people in a way they can understand it. People learn something new, there is less room for misunderstandings, and it makes future communication more effective, once everyone shares the same lexicon.
The angles I use to make a technical message clear to everyone are:
Form your sentences ordering familiar terms first and unfamiliar ones later
Be explicit about using new, technical concepts
Don’t fail to emphasize the most important part of the message
Explain technical terms, but keeping it short and knowing when to stop
Give context, explaining the causes and consequences in the real world
Consider the sample sentence below as part of an email to people from other departments that do not know what a CDN or a TLS certificate is. We are going to improve it following the step by step above.
We are now using a global CDN provider, so we have a TLS -certified faster website.
Form sentences ordering familiar terms first and unfamiliar ones later
Start a sentence and a paragraph with familiar concepts and words. Introduce the new, technical term later in the sentence or the paragraph.
In the sample sentence, the only relevant non-technical words are "faster website", so they must come first.
We now have a faster and TLS -certified website by using a global CDN provider.
Be explicit about using new, technical concepts
Don't use the technical words as if they were an unimportant part of the sentence. It gives the impression that the reader should know them already, which is not what you want. You want to make it clear that you are saying something new to the reader.
In the sample sentence, the qualities "faster" and "TLS -certified" are receiving the same en passant treatment, as they were both of obvious meaning. You want to acknowledge that TLS is a technical term and give at least a short, understandable explanation about what it means — e.g. it makes the website more secure.
We now have a faster website, that is also more secure with a TLS certificate, by using a global CDN provider.
Don’t fail to emphasize the most important part of the message
It is tricky to conciliate two desirable effects in our writing: starting with familiar concepts and not burying the lede (i.e., leaving the essential information of the text to the end). As a rule, the essential information is precisely the new information.
We still should try to start with familiar terms, but don't surprise the reader with new information by the end. You can give hints from the beginning of what you are going to say.
In the sample sentence, the new and important thing you want to communicate is that we are using a CDN provider. It is a technical term that you want to keep at the end of the sentence, but the reader has no clue that this is the core message until they reach it. You want the reader to know what is the new thing you are communicating earlier. In the end, it is an "improvement" to the website, so tell them that.
We improved the website to make it faster and more secure: we are now using a global CDN provider with a TLS certificate.
Explain technical terms, but keeping it short and knowing when to stop
Technology is a rabbit hole of knowledge. You don't know everything that happens from a user mouse click down to an integrated circuit's logic gate. You know only part of the path, the non-technical person probably knows a smaller part. You want to push their knowledge further, but you can't cover all that the things and the universe in one email. Choose carefully the point you want to make and the concepts you want to educate.
The sample sentence is now more organized and explaining the effects of the mentioned technologies, but the technical terms are still mysterious. A good idea is to adequately define the concepts in simple words. Both happen to be acronyms, so what if we expand it? CDN means Content Delivery Network. TLS means Transport Layer Security. The reader may have an intuition about CDN, but "transport layer" will only add more complexity. I believe a good choice here is to expand CDN, but not TLS.
We improved the website to make it faster and more secure: we are now using a global CDN provider with a TLS certificate.
CDN is Content Delivery Network, and it is a network of computers around the world that we rent to deliver the content of our website. Our users will always access the computers closer to them to load our site, so it will load faster — if compared with loading it from one single server for all over the world. The CDN provider also has a TLS certificate. TLS is a technology that encrypts the data when a computer is communicating with another. So we are minimizing the risk of a data breach when a user is accessing our web application.
It will always be a trade-off between the level of education and length of the text. I kept the first sentence untouched and separated in its own paragraph to give the reader a choice to stop reading while still getting the core message. I then added a more detailed explanation for the curious. I usually consider this a good compromise. You satisfy both the fast and the curious. But that wasn’t enough for this text.
The long paragraph trying to explain technical terms looks daunting and distracting. People can always search Google for technical terms. They could, but they won't, so better yet link them a good explanation for the curious. So let's make the second paragraph shorter while linking to longer, better explanations for the really curious.
We improved the website to make it faster and more secure: we are now using a global CDN provider with a TLS certificate.
For the curious, CDN is Content Delivery Network, and it is a service to make our site faster for users around the world (learn more here). The TLS certificate encrypts data going in and out of our site (learn more here).
Give context, show the causes and consequences in the real world
Finally, there is something completely lacking since the first version: context.
You can’t just drop the core sentence on an email and expect that everyone will understand by their own what this is coming from and where it leads. A faster and more secure website has obvious business impacts, so it is easier to situate the reader.
Here is how I would write the whole email (notice that I leave the technical explanation to the end, so only the curious get to it and only the really curious will click to learn more about it):
After discussing technical possibilities to increase the conversion of our site visitors into users, we found and implemented a great way to do it.
We improved the website to make it faster and more secure: we are now using a global CDN provider with a TLS certificate.
Now more users will stay on the site and navigate more on it because it’s so fast, also it will probably improve our ranking in Google, as it favors fast sites. As bonus, there is less risk of data breaches and fraud using our site.
For the curious, CDN is Content Delivery Network, and it is a service to make our site faster for users around the world (learn more here). The TLS certificate encrypts data going in and out of our site (learn more here).
