DEV Community

Cover image for Software Architecture Documentation - The arc42 Notion Template
Anton Reindl for Mindfuel

Posted on • Updated on

Software Architecture Documentation - The arc42 Notion Template

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:

image


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.

Image description


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)

Collapse
 
lnje profile image
Leander Nedergaard Jensen

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.

Collapse
 
areindl profile image
Anton Reindl

It's fixed!

I recommend you to use this one now: antonreindl.notion.site/Arc42-Arch...

Collapse
 
gernotstarke profile image
Dr. Gernot Starke

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!.

Collapse
 
areindl profile image
Anton Reindl • Edited

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:
Screenshot

Why we still like Notion + Arc42 docs:

  • we can very easily comment and collaborate to parts of the docs (e.g. to clarify questions, assign work,...)
  • it's accessible by everyone
  • chapters can be assigned to owners / stewards
  • the Notion search and the linking improved a lot
  • Notion now has a open API letting do a lot (if needed)
  • we can embed drawings (e.g. from LucidCharts) that get updated automatically

I will update the article and also share the template soon.

Have a great day.

Collapse
 
milgner profile image
Marcus Ilgner

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?

Collapse
 
areindl profile image
Anton Reindl

Notion changes how they are managing public links. Here is the new version: antonreindl.notion.site/Arc42-Arch...

Collapse
 
gernotstarke profile image
Dr. Gernot Starke

thanx Anton for the praise and the credits, really appreciated.

Collapse
 
gledros profile image
Gledros

Thanks for the template! It's really useful πŸ‘Œ