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:

https://www.notion.so/mindfuelai/Arc42-Notion-Template-b3662172ccec40e69a9c3d64ef2c6223

image

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.

Discussion (4)

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 Author • Edited on

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
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 πŸ‘Œ