Architecture as communication: what voice do you write in?

Which voice do you use when you write about technology architecture? Do you use the voice of the relentless pedant who is determined to share every last technical detail, regardless of whether your audience understands or cares? Or do you use the voice of the patient and diligent educator, who helps people understand why they should care about these technical details? Do you use the voice of the exuberant evangelist who can’t figure out why nobody finds the topic as exciting as they do? Or do you use the voice of the grounded visionary, who paints a picture of the future which gets people excited? Do you use the voice of the weary cynic who doesn’t expect to be listened to, but wants the chance to say, ‘I told you so’? Or do you use the voice of the concerned and persistent stakeholder, whose mixture of passion, reason and commitment convinces others to listen, pay attention and act?

In the HSBC Technology Architecture team, we aim to live by the principles of Zang Jing Ge: technical excellence, leadership power and communication mastery. Each of these principles comes with its own challenges, but communication mastery can be particularly difficult, especially in written form. For everybody in the Architecture team, including me, it is a constant struggle to get thoughts from our heads into the heads of others, and, through writing, to pull off this trick of telepathy over time and space.

This isn’t so much of a problem in face to face, spoken communication. It is common to see architects who would not claim to be great presenters adapting their voice to an audience in the same room (or, today, the same video conference): they are animated and engaging; they know instinctively when to sit at the table and when to leap to the whiteboard; they respond to the sight of confusion or comprehension in the eyes of their audience. They get their message across - not always, and not perfectly, but usually well enough.

But transfer this communication to the page and the message all too often dies: animation and engagement are replaced by a flat recital of facts; diagrams provide an info-dump rather than enlightenment; and it is up to the reader to do the hard work of extracting meaning.

One answer to this challenge might be to ditch all written communication, and replace it with face to face engagement. Unfortunately, this does not scale across time and space: even with modern collaboration technologies, architects cannot be everywhere at every time. Part of the magic of writing is that it is always available, always ready to be read.

However, we can draw from the idea that it would be best if we could always talk face to face: we can summon our audience to our mind’s eye, and we can write as if we are talking directly to that audience. We can adopt the voice that works best for that audience.

Are we documenting a design for people who will use that design to build something? if so, we are probably talking to technical peers, albeit in different roles to us. How would we normally talk to them? What would we expect them to understand and what would we expect them to need help with? What would they normally ask us? What do they care about most? This sounds like a job for the voice of the team member who leads the reader through a chain of technical reasoning.

Are we defining architecture guidance for someone who wants specific answers to specific questions? If so, we are probably talking to technical peers again, but peers in a hurry. How can we help them get to the right answers in the fastest way? What do we want them to learn on the way? This sounds like a job for the voice of the technical expert who shares the most useful and relevant knowledge.

Are we helping a senior audience take decisions? If so, we are probably talking to people who are above us in the hierarchy, but who don’t have the technical skills we have. What do they need to understand to make a good decisions? What is their starting point for understanding? This sounds like a job for the voice of the respected technical advisor (who probably put a tie on this morning).

Like many attempts to master written communication, finding the right voice can mean that our writing takes more time and effort. We may even need to produce different versions of our material in different voices for different audiences. But, like all written communication, we should remember that our goal is not to save time for the writer, it is to create time understanding for the reader.