Why Documenting Software Architecture Sucks and What Solution I’m Prototyping
We all like good documentation, but most of us don’t actually put in the effort to write it. Why? Firstly, we’d rather spend our time actually building stuff. But more importantly, for all the time put into it and putting up with various drawing tools, it might be out of date by the time someone needs to look at it. Worse, there’s no way of telling it’s out of date.
But let’s break this down even further:
- The frequency with which documentation is used is way too low for most projects to be worth the effort
- Most methods like scattering diagrams through Notion don’t scale well
- You have to manually write this documentation and it’s labor-intensive, skilled work to do so
- Only developers can derive use from it, so it’s hard to get buy-in from the rest of the organization
What if we could
- make the documentation more frequently useful, also for non-developers?
- automate part of the work, with manual work only giving you bonus insights?
- query the results, so you can filter for answers to questions you need solved?
- produce a single, nested diagram that show how all different pieces of the system connect?
That’s what I’m prototyping in my spare time using the Zig programming language. First, it’s a personal exploration in Data Oriented Design, to see performant I can make this to support huge, automatically generated diagrams, merged with human data. (My first test with 1,5 million nodes loads in 5 seconds for now without almost no optimization work.) Also, I did some first experiment performing static analysis on a real-world web code-base and see if I can show which screens in the front-end read and write what kind data from the back-end through which code paths. This would make this a new, customizable way to easily navigate large code-bases.
Along the way I’ll be posting about lessons learned in parsing, how simple code can be very performant, debugging, profiling and much more!
Keep in touch if this resonates with you and see you soon!