Same news, wrong words
A developer tells the college manager: "The server threw a null pointer, so the session expired."
The manager does not understand a word. Then the developer tells a team member: "Some people cannot log in. We will fix it by Friday." The team member wants more detail: which people, and what is the cause?
The news was right. The words were wrong for each person. Good communication means choosing the words for the listener.
Key words
| Word | What it means | Example |
|---|---|---|
| Audience | The people you are talking or writing to. | Students, developers |
| Tone | How your words sound: friendly, formal, urgent. | Please try again |
| Jargon | Special words that only experts know. | null pointer |
| Release notes | A short list of what is new or fixed in a version. | Version 2.1: dark mode |
| FAQ | Frequently asked questions: a list of common questions and answers. | How do I reset my password? |
| Screencast | A video of a screen, often with a voice explaining. | A 2 minute how-to video |
| API | A way for programs to talk to each other. | A weather service |
| API contract | A file that describes an API so that programs can read it. | An OpenAPI file |
The cells students fill in are left blank in this preview.
Ways to communicate
| Group | Format | Good for |
|---|---|---|
| Speaking | Face-to-face | A quick talk, a difficult message, building trust |
| Speaking | Remote conferencing | A meeting with people in other places, with screen sharing |
| Written | Blog | News and stories for a wide audience |
| Written | Formal report | A full record for managers, with facts and what was decided |
| Written | Technical documentation | How the system works, for developers |
| Written | Release notes | What changed in a version, for users |
| Written | User guide or help file | Step by step help for users |
| Written | FAQ | Quick answers to common questions |
| Visual and audio | User demonstration | Show people how to use it, live |
| Visual and audio | Screencast video | Show the steps, for people to watch later |
| Visual and audio | Narration (a person or a computer voice reads the words aloud) | A spoken guide, also for people who cannot read the screen |
| For programs | API contract | Tells other programs exactly how to use the API |
The cells students fill in are left blank in this preview.
Tone and words
Choose your words for the listener.
For a non-technical person: short sentences, everyday words, what it means for them, what to do next. For a technical person: exact names, numbers, steps and links.
Be polite and clear in both. Do not make a user feel stupid.
One problem, three messages
| To whom | Message |
|---|---|
| A user | Sorry, the app was not working for about an hour this morning. It works now. You do not need to do anything. |
| A manager | The login service was down from 9:05 to 10:10. About 200 users were affected. The cause is found and the fix is already in the app. |
| A developer | Auth service pods ran out of memory at 09:05. Raised the limit and added an alert. See ticket 412. |
The cells students fill in are left blank in this preview.
Quick check: choose the words
Have a go
Quick check: choose the words
4 questionsYour answers are marked here and are not kept. A college account keeps every student’s marks.
A contract for machines
A person reads a user guide. A program reads an API contract.
It lists each address, the methods it allows and what it sends back. Because it is written in a strict format, tools can read it. They can make code, tests and documentation from it.
Try it: a tiny API contract
contract = {
"paths": {
"/users": {"get": "List the users", "post": "Make a new user"},
"/users/1": {"get": "Show one user"},
}
}
for address in contract["paths"]:
for method in contract["paths"][address]:
print(method.upper(), address)
# A program just read the contract. Add a delete line for /users/1 and run again.