Big fan of C4. It's so simple most devs can contribute once some groundwork (initial diagrams) are done. Benefit is that software architecture is owned by the team, not just the architect.
Haven't used arc42. Seems mostly a German thing. Has anyone outside German speaking countries experience with it?
I like the concept of C4, but when I was using it, I struggled a lot with the feeling that we never really ended up creating diagrams that we'd later use. As in, we'd have a diagram in the documentation, and maybe I'd look at it occasionally if I wanted to remember the name of a particular component, but most of the time when we actually wanted to discuss architectural decisions or explain the system to a newcomer, we would just draw new diagrams on a whiteboard somewhere and discuss those instead.
The C4 model felt very comprehensive, but by being comprehensive, it failed to actually represent the salient points of the systems we were describing. Move up a layer, and you failed to capture some extremely relevant detail, move down a layer, and you had a bunch of extraneous information all over the place. In practice, most of our diagrams would be zoomed in on a handful of components, and represent other components as a kind of convenient lie. Which obviously wouldn't work if you wanted to understand the whole system at once, but that was rarely out goal when using diagrams.
I think it just felt more focused on the formalism rather than the expression, like drawing flowers according to a guide for drawing roses, and then getting into difficulties when you need tulips.
In my experience, our internal documentation had two tangible benefits.
The team explaining to itself what they were working on. That process was the value. Consensus and alignment. Akin to forging culture. The artifacts generated were ephemeral. Basically performance art.
Managing upwards. PHBs want to see pretty pictures.
Or just about the fact that in large enterprises a lot of the diagrams are owned by architects, and they're done in some esoteric inscrutable format where only the architect can make changes and updates to it _after_ talking to the developers.
I don't think this was a knock against developers.
In day to day work, checklists and Standard Operating Procedures are much more useful than diagrams.
If there's a yak-shaving exercise, write it down as an SOP. It'll become obvious if the process is flawed or a target for automation.
If making schema changes, document exactly all the steps required to integrate, test and deploy the change. It's complicated and easy to screw up - but a checklist can prevent the silly mistakes tired devs make.
The Checklist Manifesto [0] was written by a surgeon and has been shown to drastically improve surgery success rates. I'd love to see more checklists documenting development procedures - many of these could be shared as best-practice.
In a sense, true. Diagrams can be part of an operating procedure however - why not even write operating procedures for architects? Checklists to ensure they've consulted with developers, product owners and site reliability engineers. Checks to ensure the diagrams are up-to-date and actually useful.
Over the decades I have come to dislike templates and various architecture formats, I seem to always waste time catering to the tool and format and not enough time communicating what’s important.
I mostly do free-form diagramming, mostly of process level architecture and integrations.
I haven’t looked at class level diagrams in years, which maybe says something about the limits of OOP and composition over inheritance.
On the data side I do like to have a stripped down ER diagram. By stripped down I mean a focus on the key tables and relationships, not every little table and key out there.
The purpose is always to show how data flows, where bottlenecks may be, how scaling happens, and how other non functional requirements are satisfied. Try to keep them simple and to the point, and do try to maintain them (at a minimum, date them!).
Outside of something specialized like a sequence diagram I actually usually just use Keynote.
I have used a sort of "UML Lite,"[0] from time to time, but that's about as formal as I get.
Normally, I have some kind of "block diagram," on what I call a "napkin sketch."[1]
A lot of documentation is in my head.
But I also tend to work on my own, or on standalone modules.
When we have a team (and I used to work for a Japanese engineering company, so this goes double), the standardized methodology becomes quite important.
> Over the decades I have come to dislike templates and various architecture formats, I seem to always waste time catering to the tool and format and not enough time communicating what’s important.
This is interesting, because I often find the opposite; that without a template or format, I spend too much time worrying about how to structure what I am creating instead of getting out the content.
> An proven approach to structuring software architecture documentation is the arc42 template.
404 Page not found
Here's a working link to the overview in English (the other links seem to be for the German site), in case anyone is curious: https://arc42.org/overview
As for documentation in general:
- in my eyes, documentation that is "live" is the best (e.g. ER diagram of your DB, generated network topology diagram, like in Apache Skywalking and so on), though you can't generate everything
- documentation that people care about and that isn't cumbersome to work with and can be searched (e.g. text based formats instead of niche tools or binaries) is also good
- documentation that's mandated in a top-down approach, using overcomplicated frameworks or tools, with people who don't care or don't see value in them, or won't update it (or even know that this should be done) is a waste of time
- code isn't enough either, something like ADRs (https://adr.github.io/) and comments/issue management systems that explain business requirements, or stuff around the code (the WHY? not HOW?) is still needed, but again, only if people care
- people won't always care, you'll sometimes have to work with incomplete information, it will be a total pain, sometimes people won't even realize or want to fix this
- also, if you do have documentation, please make sure it's accurate: it should be a look at how things ARE, not just what they SHOULD BE (if your system is a mess, maybe have both descriptions, not just some idealistic view)
C4 is somewhat nice bzt kind of optimized for the monolith. (I actually do like monolithic architectures and quite a free applications fit there ). It just isn’t great if you want to document pipelines etc.
As with arc42 a colleague phrased it best: “it sounds good, but I have yet to find a good arc42 document“
I have adopted over the last two years to use ArchiMate for application architecture and that works surprisingly well.
I love the idea of sparse templates like this one. A list of sections you might one day populate. That makes it a helper, not a dictator, of how I document.
In my experience as a former head IT architect, the value of an architectural process is in management and communications. For example, finding out and documenting where your thought leaders are going (a technology acquisition plan) and how they plan to get there (a technology implementation plan). Those are from COBIT 4 BTW.
It's like code... code can be out of date after a while, too. The question is how easy it is to keep it updated and current. I think that's the biggest argument behind diagrams as code. Imagine you throw away your codebase each time you deploy your executable.
> It's like code... code can be out of date after a while, too. The question is how easy it is to keep it updated and current. I think that's the biggest argument behind diagrams as code.
I agree that documentation is nice even with the maintenance burden, but most would be surprised at just how much outdated code is out there. If many struggle to keep even their code up to date and not full of CVEs, what makes you think that they will also be able to have up to date documentation?
> Imagine you throw away your codebase each time you deploy your executable.
Honestly, I'm tempted to do this sometimes.
For example, consider splitting up monoliths and replacing them with many smaller services. If there is a problem with updating one part of the system, it can be left to slowly rot in the backlog, until it becomes a priority, at the same time without blocking doing the things that matter in the other parts of the system. Code should be not just easy to read and change, but also throw away. Not only that, but some more modern frameworks are just less painful to work with than the old ones (e.g. no more XML configuration hell) and you also often realize that you can do things better than the first implementation.
In a sense, one can say the same about docs: make it a Markdown file when you need to write something down, that can be easily changed/replaced and included with a merge/pull request, as opposed to some 50 page .docx file with no version control in some random network drive subdirectory.
Don't tell me it's impossible, tell me "I can't do it"...
We had architecture sketches (informal, but highly taylored to show the gist of a system) that stayed valid and were used from after the first prototype to well after release, over a course of more than five years. It was a system of six embedded processors, 2 FPGAs, 5 different bus technologies, (luckily only) two different endianesses and coding and debugging would have gone horribly wrong without that overview sketch of just enough detail. There are cars in your town that drive around with it for a dozen of years now.
This argument gets thrown up by someone nearly every time documentation gets mentioned.
1. Does it matter if not entirely accurate with the as-is? It showed the previous state or intention, that is typically very useful and a lit better than nothing.
2. Your unit test are out of date when your change code yet that typically gets updated, or new tests added, and is typically more work than updating the docs.
3. If what you document is so wildly different to the solution, you're probably documenting too much detail (this is where most junior devs go wrong), if it's that your arch has actually radically changed it sounds like your documenting too early, do you do spikes etc to figure out your arch before you commit to it?
You mean because of a svn:needs-lock? That was a useful feature for really unmergeable (binary) files which is not suppoted by Git because of its DVCS nature.
Coding is the tip of the 'working in software' iceberg. If you don't see value in being able to communicate the reasons behind the technical choices and trade-offs you've made, both within your own team and to other stakeholders then you'll quickly find that your coding time is quickly eaten up by people asking you to explain it.
If you value periods of deep focus or 'flow' then believe me, having concise, accurate documentation that explains why, how and what you are building pays off - if only to help you separate the planning from execution process in your own workflow. I don't think any moderately complex software can be written without some degree of planning - but maybe your experience differs
This feels like another scrum workshop or whatever they teach to non tech managers. Forcing a specific workflow without ever explaining why (context -> containers -> components -> code), not a single mention about the problem domain but just a generic framework you are expected to fit all problem domains into. You learn more about the framework before you learn about the problem. Example:
"Here's a container! It is either a Server-side web application, Client-side web application, Client-side desktop application, Mobile app, etc etc". Okay why? Why are you making this distinction? Why not just call it a web server, a web app, a mobile app? What could this concept of 'container' be so useful that you have to invent it and make everyone internalize it? Does it contribute to the discussion? Are you trying to arbitrarily force labels onto things so you can use the same lingo to talk about every problem?
It's called abstraction, which is used when modelling categories of things, you do it lots when you write code right, so things are reusable.
Like you probably have something called an iterrable in your programming language of choice, so why not just call it a linked list, or a vector, is basically the argument you're making in my opinion.
To be fair, I do find some modelling languages do disappear into too much abstraction, they basically end up like being a Upper Ontology [1] and lack instances/examples that make them approachable in practice.
Haven't used arc42. Seems mostly a German thing. Has anyone outside German speaking countries experience with it?