Contents
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.
Determine target audience
To understand the knowledge level and expectations, you should also mention in the beginning of the document who is the target audience for whom the document is written. Knowing the target audience also helps frame which concepts need detailed explanation and which concepts
can be taken as prerequisite knowledge that the readers already have. For example when writing for Customers it's important to explain the outer boundaries and omit details on how exactly different technologies can realize the target architect of the software. When writing for developers or development managers its the opposite. We need to emphasize on the technologies that could be used to realize the architecture and can incorporate those in the Architecture diagrams. As an example, if our target audience is Customers/business leaders and if we say or show in diagrams that we are going to use Asynchronous messaging to dispatch requests, we need to explain what is Asynchronous messaging and its advantage. But if the target audience is developers then we can assume that they already know this. So ask the question yourself who should read the document.
Define Goal and scope of the document
To chalk out what will be the level of detail you will write the document. To find out you need to ask yourself why you want your audience to read the document and what you want your audience to know.
Gather information
Many times you are not the creator of the architecture because you need to write about an existing software application/system. For that you need to gather any existing document first. Understand the document and extract information.
But existing documents could be outdated, so you need to work with the software to understand how the basic building blocks work or how each part works in detail. This will revalidate what is written in the document and also help you find the deviations that occurred in the software from the document. It also allows you to understand the Actors and roles of the Actors of the system.
Interviewing people who developed the system or who are currently using and developing the software follows next. That's how you can find the latest information about the current state of the software. When you walk into the interviews try to prepare some models according to your understanding that you can present to the interviewees and validate what you have understood is correct or not. If you can arrange for a series of small interviews then it would not be boring for the interviewees and also easy for you to grasp and remember what has been discussed. Show the models to them and take feedback. Write down your newly gained knowledge and also incorporate it in the models/diagrams. Next time you can present the upgraded and/or detailed version of the diagrams to the interviewees. This also helps to keep the continuity of the interview series. prepare question sets and ask precise questions but try to make it look like a conversation. Using diagrams gives you an advantage of something to point at when talking about it and also establishes the common terms and vocabulary. In the interviews you will get different pieces of information that does not stick together because they belong to different levels of detail and different parts of the software system. you need to structure those information accordingly, identify gaps and then prepare questions to be answered by the interviewees in the next interview to fill the gap.
Structuring, Formatting, Writing and Tools
Introduce chapters to describe each part or differentiate between overview part and detailed explanations. You can use a few points to determine how you can segregate the whole content in different chapters. The following could be good candidates for a separate chapter: An obvious part of the architecture that need to be explain in detail, and introduction and explanation of the prerequisite to understand the topic, Concept(s) used in the architect, general building blocks that has be reused in different parts of the architecture, the solution of the problem to be solved, the wrong solutions/decision that need to be avoided. In each chapter introduce sections. An introduction section should outline the overview, provide the context and the motivation for the reader and explain why this is important. In the beginning of each chapter you can briefly explain or reiterate what the reader will be able to learn when they finish the chapter and what to expect in the chapter, it will act as a motivation to the reader. It's a good idea to provide a summary section for the readers to recap. If you write an introduction chapter then all the context, the outline of the book (how the content is structured) and the basic concepts needed can be written, the assumption taken can be inked. An abstract section is like a summary but comes at the beginning, it's a more compact version of the summary and can contain the claim which you explain in detail in the chapter. In summary you can conclude the points that have been used to justify and explain what you have claimed in the abstract. A summary chapter can contain the most important parts written in brief with the most important diagrams. This Is written for the reader who wants a crash course without reading the whole document. Also it's a good idea to provide a glossary of acronyms that you could use throughout the document as short hands of big names. But remember, when you introduce an acronym for the first time in the document write its full name with the acronym.
Try to include the reasoning behind the solution the architecture provides. why it was needed, what are the other options and why this solution was chosen, what were the requirements. Include examples whenever possible, it helps readers understand and visualize using a real world scenario.
Use a table of index, figures index, glossary etc. to cross link parts of the document. Specially if you are referring one part from another within the document the indexing and numbering helps and makes it non-ambiguous for the reader.
If you are preparing a large document these approaches also help to work on the document as a team that you can split while writing and merge later.
Also add citations and links to documents you have used from others in your document or refer to others work as a supporting document to establish your point.
Keep in mind that it's not about what the author wants to say but about what the readers should know/understand in the end. Put yourself in the reader's
shoes and understand what readers want to learn, what's their knowledge and expertise level. Explain the key concepts, all readers may not have the same level of knowledge and understanding. Often people have a different or an unclear understanding of fundamental terms and concepts, that they should know.
It's best to start with an overview diagram and explain the diagram to provide the basic understanding. The overview diagram should abstract unnecessary details. For example whether you use a MongoDB or a Redis multi node DBMS to keep data is not relevant in overview. You need to depict which business data is stored and which actors and/or software modules access those data. Here the business data can be depicted as data "storage" with the name of the business data. The actors and software modules become the "agents" and the how the agents access storage becomes "channel". explain each and every agent, storage and their interaction using channels.
You also need to prepare and finalize the document writing style, establish the vocabulary that will be used in the document and either explain them as an introduction or prepare a bibliography. When preparing the format and style of the document you can use templates in MS Word and use macros to update the template. Use a document template/layout with footer and header that contains document name, topic and page number. When formatting text use defined headings and paragraphs, avoid introducing your custom style and format and reuse the standards. If you use your custom style then use it in a consistent way by creating a template.
Models or Diagrams
When you create diagrams provide more focus on the self explainability of them rather to make them technically sound and making them formal. you need to find a balance among these two factors, make them semi formal but don't make it completely technically unsound. You can use block, class, sequence, state, activity, E/R diagrams depending on the need and level of detail.
when you add diagrams in the document try to use vector graphics format if possible. In MS Windows: WMF / EMF is a container format that can be
used for vector graphics. MS Visio can export EMF easily. in MS Word use the "Insert and Link" option when inserting a diagram. It's a better idea to use a common paragraph style for diagrams and provide a caption with a figure number.
A model/diagram centric approach of writing documents first provides an overview diagram and starts describing the diagram. Then in the subsequent chapter it shows details of the parts of the diagram and describes those diagrams. using a series of diagrams from abstract to details the whole software architecture is explained. It helps readers to depict the system in mind and eliminates ambiguity that may occur by just reading the text. For authors it becomes easy to structure the document and write the text always keeping the diagrams in mind. In each level of details the writer should decide which type of diagram makes most sense. When you create the diagrams keep the persona/agent in mind who is initiating the work flow or interacting with the software. For example, the level of details for developers, Admins, Consultants, End users will be different. The level of abstraction and detail depends on the purpose and aspect (what you want to convey) and audience (to whom). Always remember the more abstract a diagram is, the more imperfect it is compared to reality, but that does not harm when a detailed diagram follows. When presenting a series of diagrams from abstract to detail you need to link those diagrams so that the reader can easily navigate from abstract to detail. you should use constant labels, similar layout even colour code to show the relations among diagrams or parts of it. try to avoid acronyms in the diagram labelled whenever possible it increases diagram readability as the reader does not have to remember the mapping of the acronym to its full name and do not have to go to the glossary.
Diagrams also help when defining the basic concepts and terms. You can provide an example that uses the concept and draw instructions to show the concepts used in the example.
Reviews
You need to involve all stakeholders to review the document sooner and not when you have finalized everything.
At the end writing an architecture document is a small project that requires planning like any other project. You need to plan the phases like gathering information, scheduling interviews, establishing the document outline, writing the document introducing and interacting with stakeholders, collaborating with document contributors, preparing drafts, incorporating reviews and finalizing and publishing the document.