If you need to document your planned or existing software architecture, it’s often difficult to know where to start. And even if you have thought about it some time, you probably don’t know how to structure your text so that a novice reader is able to follow you.

There are a few books out there whose autors describe very well how to write such software architecture desciptions. For example, have a look at “Softwarearchitekturen dokumentieren und kommunizieren” (ISBN-10: 3446443487). They explain in detail which contents are required in which order. However, who has time to read these books and find the relevant paragraphs?

For this reason, I put together the most important parts below. Of course, this overview is from my point of view. Nevertheless, it should give you a faster introduction to this topic compared to finding and reading the relevant paragraphs of interest in a book of many hundreds of pages.

I like templates (but not in the form of cooking or baking recipe). Templates ease the start of writing. They give you a predefined structure that you could easily follow. In this way, you know what to write and in which order. So, here is my template for describing an arbitrary software architecture:

Introduction (without a section title)

1. Introduce the domain of application of your architecture so that the reader knows what he or she should expect from your description. Otherwise, if you do not give context, the reader might expect everything, but probably not what you want him or her to tell.
2. One sentence about the content of each following subsection so that the reader knows what you will describe in which order.

Architectural Drivers

1. Requirements on your architecture, including corresponding justifications
   1. Use phrases like
      • “we expect from your architecture …” or
      • “our architecture must be able to …” or
      • “our architecture should …”
2. Constraints of your architecture, including corresponding justifications
   1. Your software architecture will not represent the one-and-only architecture which matches to all of the problems in the world. Hence, you should name the constraints of your architecture.

Components of your Architecture

1. Describe each component in a separate section
   1. Give it a name
   2. Describe what the component represents (and, if useful, what it does intentionally not represent)
   3. Describe the structure of your component, including corresponding justifications
   4. Describe the responsibilities of your component, that means, what are the specific tasks of the component, including corresponding justifications
   5. Describe what tasks are intentionally not part of the component