Communication Patterns

My personal notes on the book Communication Patterns.

1. Communication Essentials

• Know your audience: always keep in mind how is going to view and read your diagram. Make a list of the roles that view of your diagrams, and tailor you message accordingly. The C4 context diagram is a good example of a diagram that is useful to most audiences.
  • Always ask the following questions about your audience:
    • What do they want from you?
    • What do you want from them?
    • What is their technical understanding?
    • What level of detail they need?
• Do not mix different levels of abstraction: this leads to clutter and confusion. Use different levels of abstraction across multiple diagrams. Again, the C4 model is a good example of this.
• Representional consistency: link discrete diagrams together so your audiance can navigate between them and see how they fit together. Use hiperlinks and labels when possible.

2. Clarify the Clutter

• Avoid color overload: only use the colors needed to convery your message, and be consistent using them.
• Avoid boxes in boxes in boxes: when you have too many boxes, their many lines become visually confusing. Labels or notes may be able to replace bloxes.
• Avoid relationship spiderwebs: when relationships cross over each other or even cross over other components in the diagram, you end up with a spiderweb of confusion. It is not clear whether this crossing has meaning.
• Balance text: too much information in a diagram obfuscates the intended message. Notes or footnotes may be leveraged.

3. Acessibility

• Accessibility isn’t just for those with temporary or permanent disabilities or special needs. - your diagrams and visuals need to be accessible to people with different levels of knowledge, business functions, and familiarity with your product or domain.
• Do not rely on color to communicate: if colors are indistinguishable, any meaning ascribed to them is lost. Use patterns, contrast, symbols and an accessible color palette.
• Include a legend: while you should be careful to not clutter your diagram, it is better to be explicit - you shouldn’t assume the audience knows all the terms, notation and acronyms in a diagram. You can also link to the legend, or replace it with labels in some cases.
• Use appropriate labels: make sure text and labels clearly communicate your message, and are placed close (with enough whitespace) to the component or relationship you are labeling.

4. Narrative

• The big picture comes first: you want to tell a story, and you need to start from the beginning - in this case, with a high-level architecture or context diagram, so you can give your audience enough context to follow the narrative.
• Match the diagram flow to expectations: a logic order of diagrams must follow.
• Display clear relationships: differentiate hierarchical, sequential, causal, proportional and spatial relationships. Use labels instead of multiple arrows if needed.

5. Notation

• Do not use icons to convey meaning: like the new macOS Tahoe, adding icons actually increases complexity and may overload your audience without giving any benefit. Use icons only in addition to the information you want to convey.
• Be consistent with symbols, colors, and fonts in your diagrams.
• Do not mix behavior and structure.
• Do not go against expectations: take care to not break any common mental models in your diagrams, presentations, and so on, or risk causing misunderstanding.

6. Composition

• Visual composition helps you convey structure, relationships, and dependencies.
• Diagrams should be legible: design you diagram to fit the audience’s viewing format. Chose a readable font as well.
• Watch out for misleading composition: you need to balance abstraction with accuracy where it matters.
• Create a visual balance: symmetric diagrams help improve readability.

7. Written Communication

• Use simple language: do not try to sound clever, and avoid using idioms. When needed, include a glossary and define your ubiquitous language.
• Avoid using acronyms: when you use them, always include their definition.
• Structure your writing: the structure of ideas should always be like a pyramid - start from major, more abstract ideas before going into the minor, supporting ones.
• Observe the syntax of technical writing: the syntax of technical writing is important to ensure that your writing is clear an informative. Choose strong, precise, active verbs (words that describe actions, states, or occurrences), short sentences, precise paragraphs (they should cover one topic and include the what/why/how), consistent vocabulary, and be empathetic towards your audience.
• Tips for technical documents:
  • Begin with the key points.
  • State the scope (what the document is about).
  • State the nonscope (what the document is not about).
  • State the intended audience.
  • State required prerequistive knowledge or reading.

8. Verbal and Nonverbal Communication

• Acceptance prophecy: when you think others will like you, you behave more warmly toward them and, therefore, they like you more. The opposite is also true. Becoming a social optimist, can boost your credibility and the likelihood of you succeeding in your communication goals.
• Give your full attention: give eye contact; do not use your phone or laptop when people are talking; take notes using a pen and paper (or tell them you are taking notes using a device); don’t interrupt them when they are speaking; ask clarifying questions; repeat your understanding back to them to ensure you have understood.
• Use body language and gestures: explanatory gestures can help people better understand what you say, whereas power gestures express dominance and authority.
• Be aware of your biases.
• Take into account cultural differences.
• You ideas and solutions need to be aligned with your audience’s goals to be persuasive. Therefore, you must understand their needs and concerns, and communicate that you have this understanding.

9. The Rhetoric Triangle

• Devise by Aristotles, it is a framework to understand the elements of persuasive communication:
  • ethos, the credibility and trustworthiness of the speaker;
  • logos, the logical and rational argument presented;
  • pathos, the emotional appeal used to engage the audience.
• Establish your credentials: highlight your qualifications, experience, awards, publications, and so forth.
• Use trustworthy sources: cite them when presenting your work.
• Be transparent: communicate your motivations to your audience.
• Tell a story: stories can help explain complex concepts and make a message more relatable and memorable.
• Speak from the heart: be authentic and sincere - telling stories always helps with that.
• Use vivid language and strong imagery: metaphors, similes and analogies can help paint a picture in the audience’s mind and evoke emotions. Examples: personify nonhuman things; hyperbole; strong action words.
• Use data and facts: use data and facts to support your views, and cite your sources.
• Make logical connections: organize your content in a structured and logical manner; use transition words and phrases (therefore, consequently, etc) to show the logical connections between ideas; give examples to illustrate the conections, and use diagrams and flowcharts make content easier to understand.
• Use reasoning and argumentation: your audience needs to understand your reasoning. Leverage techniques such as trade-off analysis and ADRs.

10. Knowledge Management Principles

• Products over projects: organize documentation by product - projects are transitory, or at least more transitory than products.
  • Centralize documentation and organize it by product.
  • Group (tag) artifacts by product.
  • Use folders and hierarchies strategically: keep the product at the highest level possible.
  • Organize documentation into perspectives that address a stakeholder concern (perspective-driven approach).
• Prefer abstractions over text: use lists, tables, charts, graphs and diagrams to represent important ideas. People may glance over text, but still read these specific elements.
• Perspective-driven documentation: it focus on who you are communicating with and why. A perspective is a collection of artifacts that address one or more concerns of a particular stakeholder.
  • The perspective author (an architect, or a dev) has to collaborate with the stakeholder to identify the artifacts that must be created to address a concern.
  • Different stakeholders have different needs, so their perspectives will differ: the C4 model fits well here, given that it illustrates an artifact at four different levels.
  • When creating a perspective, do not duplicate artifacts - embed them in each perspective. You may also embed perspectives into another perspective (fractal perspectives).
  • Common perspectives can be arranged into templates or checklists once you have identified patterns.

11. Knowledge and People

• Get feedback early and often: follow the agile way - work iteratively and incrementally. Frequent sanity checks help you steer the work in the right direction. You will then be able to identify issues and errors earlier, ensure alignment, establish a dialoge with the stakeholders, and identify risks.
• Share the load: avoid using proprietary formats to increase the accessibility and lower the barrier to contribution.
• Just-in-time architecture: don’t decide and document what you think you will need in the future, but only what you know you need now.

12. Effective Practices

• ADRs: a record of an architectural decision and the reasoning behind it that can also be used in the decision-making process itself.
  • Common ADR structure: identifier and title; status; context; evaluation criteria; options; decision; implications; consultation (inputs from others).
  • A decision can be changed, but an ADR can only be superseded.
• Architecture characteristics: they are the priorities for your system or product. They are often associated with nonfunctional requirements.
• Documentation as code: create your documentation in the same environment or IDE that you use to create your code, using a markup language such as Markdown, and store it in version control, automating most processes (publication, validation, etc).

14. Remote Principles

• Meetings to sync: use sync communication to build rapport and generate ideas, and async communication to report progress, gather feedback, and disseminate information.
  • Enhance meetings by staging the goal(s) for the meeting; set an agenda, including timings; set the expectations to support the meeting; invite only the correct atendees; plan and put in place any async communications needed before or after the meeting; document decisions and actions from the meeting and send them out after the meeting; manage attendees’ energy by planning breaks.
• Async to think: an advantage of async communication is that the recipient chooses when to consume the message (and respond if required). This can lead to a higher caliber of response, likely better thought through or more researched.