Guide to Software Architecture Documentation | Hacker News Reader

Guide to Software Architecture Documentation

workingsoftware.dev

239 pointskiyanwang52 comments

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?

C4 is where it’s at. Simple enough to learn but comprehensive enough to be effective.

> "It's so simple most devs can contribute"

Oof... a lot to unpack in this phrase.

You would be surprised to learn how much "devs" actually know.

They may even recalibrate your ego a little bit if you were open to receive feedback.

Those "devs" are the people that have to turn architectural documentation into reality, sometimes ignoring it completely.

I think they’re talking about the difference between senior and junior devs here.

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.

Exactly, I'm a dev myself.

"most devs" was meant as "most fellow devs". My whole point is to make architecture documentation a team activity.

I base my architecture docs off the arc42 document. It’s useful as a base but always needs adapting to the specific system being documented.

Do you have any tools or guides to recommend for devs wanting to learn how to create "C4" documentation?

There is https://c4model.com/

This is helpful, thank you

We created an interactive Miro workshop for teaching the C4 model structure.

https://miro.com/miroverse/c4-model-getting-started-workshop...

awesome, thank you!

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.

Also changes to the diagram (at a certain resolution) require looping in specific senior people for review.

All of the arc42 documentation is written in English, and the template itself is available in seven different languages.

See, e.g., https://docs.arc42.org

Apart from one of the founders (me) being German, it's no "German thing", but hopefully helpful to all kinds of systems.

Tx, good to know.

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.

[0] https://www.npr.org/2010/01/05/122226184/atul-gawandes-check...

These aren't the same type of thing. Diagrams are to communicate and discuss what could be/what is. Checklists are to remember to do things.

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.

I don't see why you're talking about operating procedures. This is about good diagram / documentation formats. Nothing to do with checklists or SOPs.

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.

[0] https://littlegreenviper.com/miscellany/swiftwater/the-curio...

[1] https://littlegreenviper.com/miscellany/forensic-design-docu...

> 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)

This is all I'm typically looking for to fully grok a system:

-Working (or whatever is close) application I can play with (sandbox ideally)

-Readme with where all the docs are

-State Diagram, Flowchart, UML, (show me how & where data flows)

-Repo links (Maybe a cloned VM of a dev environment)

I‘d add Dockerfiles and infrastructure yamls to that list.

For me that’s where diagrams can really shine, plus things like a project‘s roadmap

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.

Kind of ironic to see dead links in a good documentation practices article.

I have used a combination of C4 and arc42 for a number of projects and it is working well for us.

Do you use them in the way described in the article? I'm interested in using both but have basically YOLOed in the past.

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.

One question though:

“Don't includes Tutorials or Q&A sections”

Why?

Diagrams are where architecture goes to die.

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.

What you're talking about sounds more like IT estate change management. I think this is about software construction.

As with all documentation.. it will be out of date after a while.

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.

"Don't tell me it's impossible, tell me "I can't do it"..."

That's just rude so I'm not going to bother replying

So what?

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?

>Does it matter if not entirely accurate with the as-is?

Yes. I've lost more of my life to out of date misleading documentation than to documentation that didn't exist at all.

Unit tests are tied to the build process for exact reason that they need to be updated with the code.

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.

Are there any other resources in this space?

https://www.ilograph.com/blog/posts/multiperspective-diagram...

Why is there a fucking huge Register button on this web page when viewing on mobile?

If "how can I work in software without coding" was an article.

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

Yet, if you lose touch with implementation work, you will be less effective at analyzing requirements, designing and planning.

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.

[1] https://en.wikipedia.org/wiki/Upper_ontology

Reply on news.ycombinator.com