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 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 start. Simply duplicate the page to your workspace:
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 that owns the architecture and carefully instructs 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 the 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.