Documenting Software Architectures

Docs as Code with C4 and Arc42

I had to document some software architectures recently. The project consists of a mix of C/C++ and python code. It’s not a tremendously large project, but significant enough to justify having a thorough documentation what the code is supposed to do, how it is organised and who the various stakeholders could be.

I wanted to have a lightweight docs-as-code approach. I know people who have used Sphinx-Needs in the past, but this solution felt a bit daunting to me. It’s capable of a lot more of things than I’ll ever need. While searching for alternatives, I remembered that I had encountered the C4 Model and arc42 in the past. So I gave them a try. The C4 Model can easily be modelled with plantUML. There is a library for that. Further, arc42 provides templates in various formats, many of them are text-based and can therefore be put under version control.

Even though Sphinx-Needs felt like it was overkill for my task, I was tempted by trying out Sphinx. Fortunately, arc42 provides a template in ReStructured Text format which can easily be included in Sphinx. And finally, there exist plugins for sphinx to render plantUML diagrams as well as Doxygen output. Documenting the python code was almost trivial with the autodoc functionality of Sphinx.

I’m quite happy with the outcome. My solution feels lightweight, builds on open source software and is follows the concept of docs-as-code.

Notes