DEV Community

Discussion on: Software Architecture Documentation - The arc42 Notion Template

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

areindl profile image
Anton Reindl Author • 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:

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.