What to keep in mind while describing Architecture?

We need to describe Architecture on different occasions, be it requirement engineering, development or acquisition. As an architect we need to have empathy for the target audience. We need to make sure that our audience gets interest in the topic and easily understand the topic throughout. Often we can directly interact with our audience and the only form of interaction is through documentation.

To make your Architecture document understandable you need to explain the big picture, define the terms and vocabulary used etc. It's a good practice to provide an introduction of the whole system first before jumping into the specific parts of the software that you want to describe in detail. That's why, how you structure information in your document also plays a big role in understanding the Architecture document. The system structure is quite different from a software structure. system structure defines how the software runs and where and how its fully or part by part deployed. software structure on the other hand shows how its developed using different projects and modules. Also you need to describe the system the software automates. This is completely different from the system/software structure. For example if the software automates a coffee vending machine or a banking system, you first need to explain how in principle the coffee vending machine works or the banking system works in general.

Here are few points to keep in mind

• Determine target audience
• Define Goal and scope of the document
• Gather information
• Use of proper Structuring, Formatting, Writing and Tools
• Use of Models or Diagrams
• Reviews

To read details on each point read the post what to keep in mind while describing architecture