Software Architecture Documentation - The arc42 Notion Template
Tags: notion, arc42, architecture, documentation
Published: 2021-03-09 10:13:26

Our company uses [Notion](https://www.notion.so/product) as our central workspace to organize work and document things. It's a great tool and we are really happy with it. The simple, fast and yet extremely powerful user-interface was the key advantage of Notion when we chose it over the very popular [Confluence](https://www.atlassian.com/software/confluence) by Atlassian.

So obviously it's also our go-to-tool for documenting the software architecture in our projects. When we document software architecture we use the very pleasant [arc42 template](https://arc42.org/download). It was created by Dr. Peter Hruschka & Dr. Gernot Starke and is available in multiple formats. The template is free to use. 

We prepared a Notion clone of the arc42 template to accelerate your work and make it easier to get started. 
Simply duplicate the page to your workspace:

![image](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/gheobxbq382vfdmmk4fl.png)
 

* [Simple Template](https://antonreindl.notion.site/Arc42-Notion-Template-96d4cfba68f54f60a9101991f96fd1b6?pvs=4)

* [Simple Template with Help Texts](https://antonreindl.notion.site/Arc42-Notion-Template-with-help-text-3e76db1673414098b20554dffee7b8c8?pvs=4)

_____


_UPDATE from October 2023_

Our documentation was growing a lot. At some point, the single-page template was too cluttered and the loading times increased.

There we added a new and more organized template with subpages and new database. We recommend you use this one.


* [Arc42 Template with Subpages](https://antonreindl.notion.site/Arc42-Architecture-Documentation-Template-with-Subpages-b1f03844201a4d8d9998d3344eb9356e?pvs=4)


![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/i9343ntvbzsjd8ez25cb.png)


____


If you are new to arc42 I can really recommend the book *Arc42 by Example: Software Architecture Documentation in Practice* by Gernot Starke und Stefan Zörner. It helped us a lot to get started with documenting.

So here are our key take-aways:

* Be correct: name one responsible person who owns the architecture and carefully instruct others to provide chapters of the architecture documentation.

* Make it maintainable: the architecture documentation should be the single source of truth and very easy to adapt. Notion has a built-in version control that allows clear revision of chapters. Use the discussion and commenting feature to discuss architectural decisions in the document.

* Stay accessible: first of all, only document the relevant things - avoid unnecessary stuff and focus on the really important parts of the architecture. When you write documentation avoid overly complex language. Me short and precise. It's documentation, not a novel.

* Write iteratively: software architecture evolves over time. It's not something that can be done 100% upfront. It will grow together with your application. So make sure that it gets updated on a regular basis and is part of your (agile) development process.


I am happy to hear your thoughts on documenting your architecture in the comments.

_PS: Again thanks to Gernot Starke und Peter Hruschka for providing this great template for free._