Ask HN: Is there a better way to document complex software architectures?

If the code is generated from the diagrams, why check the code in at all? Feels akin to checking in the bytecode with your the java that generated it.

I’m hearing two things:

1. You want to build these diagrams faster and perhaps semi-automatically instead of dragging around boxes and lines.

2. You want them to look better and not so perfunctory. To communicate better.

There is kind of an oddball option here which I fell in love with. There’s a tool called Monodraw which is magic for making old school ASCII art diagrams. It’s surprisingly very visually compelling, easy to update and it’s just text so it can be embedddd in source code comments (no PDFs).

The best reason you might consider this over a “big” IDE-type solution is that ultimately good cogent communication requires making choices about what to highlight. An exhaustive auto generated architecture diagram in the same generic style of everything else can make one’s eyes glaze over. When you choose what to show and emphasize you can tell a better “story”.

Yes you have to keep the diagram up to date with major changes, but that’s not a problem if you lower the cost of updating and raise the visibility of the diagram by putting it in code. They even have a CLI now so you can export it in your build process.

The analogy I sometimes use is that you don't need an architect to design a garden shed, but you do for a house which is much larger, has complex integrations with plumbing, electrics etc., plus building regulations to comply with, etc. A lot of dev work, especially in smaller companies, is building garden sheds, i.e. small single purpose self contained apps, but that doesn't mean every building is a garden shed.

You can use TLA+ -- it's what Amazon and Microsoft uses.

TLA+ is a formal specification language, plain-old maths, and the tool suite includes a model checker and a pretty printer. The model checker verifies properties of your specification that you want to hold true such as liveness. And it also includes a pretty-printer for exporting your specifications into well-formatted PDF documentation.

The nice thing about writing specifications this way is that they are specific, at the correct level of abstraction for the problem, and can be verified.

I think Lamport's analogy is apt: specifications are like blueprints. If you're building a shed in your backyard then a sketch will be sufficient. There's no need to have a blueprint. If you're building a house you'll need some kind of blueprint. The software equivalent of a sufficient blueprint for building a house is a strong, static type system, unit, integration, and property-based tests. If you're building skyscrapers you need something much more formal and I think this is where TLA+ and Lean are useful.

Hundreds of full time developers?