Respect Your Audience

As you learned in ​The Four Principles of Design Thinking​, all design is social. Who will use your architecture description? What do they need to get out of it? How can you best provide the information they need most? When empathizing with our stakeholders, we identified and recorded their key concerns. We’ve come up with a plan for addressing their concerns in the architecture and now our job is to share that information.

When you know your audience, you’ll be able to create an architecture description that gives them exactly what they need. The better we do this, the more likely people are to read the architecture description, which in turn further amplifies the impact of our design decisions.

Think about your stakeholders and what they value. What are their roles and responsibilities on the project? How do they like to process information? How will this person use the information you give them? Sometimes it helps to create an empathy map of your audience to help you get started (see Activity 2, ​Empathy Map​). There’s a sample empathy map for a developer on my team.

By studying the example empathy map, we can see that this person needs a thorough document with a clear rationale since he likes to argue both sides of any decision. We can also see that this person is interested in properties related to deployment and wants technical details.

Now that we know what kind of information our audience wants and how they might consume it, let’s talk about how we can make the most understandable architecture description for them.

Focus on Understandability

Communication is king when it comes to architecture descriptions. Your audience wants to understand you. Speak the language of the domain in which you’re working to make your architecture description understandable. If your stakeholders talk about material master numbers, use their terms instead of introducing new words like product IDs.

How you choose to describe complex, abstract ideas is also important. Use plain speak and avoid jargon. Briefly define architecture concepts to ensure your reader has required background knowledge. Unless it is completely wrong, favor design terminology stakeholders already use. For example, if stakeholders prefer to discuss nonfunctional requirements then use that term instead of quality attributes. Err on the side of effective communication.

Understandability also extends to notations. Not everyone will know every design notation. This advice goes double for the Unified Modeling Language (UML). There are several flavors of the UML, and though it can express architectural ideas well, it’s not always direct or obvious. You may know exactly how to use all of UML’s 16 or so diagrams, but not everyone in your audience has studied UML as intensely. As you learned in ​Draw Fantastic Diagrams​, always define your notation and the meta-model behind it by including a legend on all diagrams.

Finally, organize your description so it’s easy to consume. Use a standard template for written documents and make it look good. Fix the alignment so it’s easy to read. Use text formatting to your advantage. Think about how the information looks in print, digital, and presentation formats. A great-looking document tells readers the content is trustworthy and was created by a professional.

You’ve learned a few techniques for documenting design decisions. You’ve also learned how to think about your audience to design an architecture description that is right for them. Next, we’ll combine these two ideas together by organizing the architecture description relative to stakeholders’ concerns.