Software is an abstraction of machine language, and diagrams are a higher-level abstraction.
The C4 model is a hierarchy of abstractions that let you zoom from the system context to the components and then the code.
Some antipatterns of communication:
- Colour overload
- Boxes in boxes, inside other boxes
- Spiderweb of relationships
- Superfluous text or descriptions
Keep accessibility in mind, for example some people are colourblind, follow A11y guidelines, etc.
Charts don’t exist in isolation so you need to provide context.
Consider how your audience might consume the diagram, on screen or paper, landscape or portrait, etc.
When communicating in written language, include a glossary when using ubiquitous language (i.e. business specific terms that might be common only if you know the industry).
When using acronyms, ensure that definitions are available. In the industry we might be familiar with SPAs, DDD and RFCs but to others it means nothing.
When writing emails or technical documents, use a pyramid to structure the information, starting with an introduction or executive summary, then branching out into more detail, and expand the further down you go. Start with the key principle, identify the logical arguments, and then break those logical arguments down individually.
Use strong verbs instead of weaker inactive verbs like be, was, happen, for example:
The error notification happens when (incorrect)
The service generates the notification when (correct)
Each paragraph should be precise, and have a single responsibility.
Prefer shorter sentences.
Use consistent vocabulary throughout.
It is also helpful to define your audience first, so that your writing can address the correct audience.
Communication is more than just words, it is about encoding a message to send and decoding the message received… that can include a wide array of things like body language, gestures, eye contact, scent, tone of voice, personal space, touch, appearance, the use of tools and props, etc. This also includes things like cultural differences, and how small things might be interpreted depending on the culture and context.
Being transparent about your motivations, biases, and conflicts of interest can help build trust with the audience.
Speaking from the heart means being authentic and sincere, connecting with the audience on an emotional level.
Get feedback early and often, if you put a lot of effort into something without feedback you often end up wasting effort and money.
Never let rank get in the way of receiving wisdom.
Book review: 2/10