Our company uses Notion 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 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. 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:
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.
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.
Top comments (8)
The linked template is not accessible. I get a message "You do not have access to this page."
How do I gain access to the template? I am very interested in using it.
Thanks.
It's fixed!
I recommend you to use this one now: antonreindl.notion.site/Arc42-Arch...
had never anticipated that people would use NotionHQ for software documentation.
Otherwise, it looks and feels awesome - but I'm afraid industry adoption might be really low. Hyperlinks between notes is mediocre. I felt locked-in, getting notes out of Notion was a lot of manual work.
In sum, it didn't work out for me (private note taking and documentation) - I switched to Obsidian and don't look back!.
Thank you for the comment, Gernot!
Over time we also gained new experience with Arc42 in Notion. When the document becoming longer and longer, Notion started becoming really slow when you scroll down and it was getting very unclear.
So I refactored the chapters to sub-pages and it helped us as lot. I attached a screenshot:
Why we still like Notion + Arc42 docs:
I will update the article and also share the template soon.
Have a great day.
It looks like the template is not publicly accessible anymore. I'm only getting the message "You do not have access to Mindfuel. Please contact an admin to add you as a member."
Is it because you aren't maintaining the template anymore or was this unintentional?
Notion changes how they are managing public links. Here is the new version: antonreindl.notion.site/Arc42-Arch...
thanx Anton for the praise and the credits, really appreciated.
Thanks for the template! It's really useful 👌