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

[luckydata]

I would use them if they existed. I usually spend the first couple months of my tenure with a new team documenting the product after I ask a few questions and inevitably people start giving me answers that are rarely consistent.

After those diagrams are created, usually everyone is SHOCKED that discussing the system becomes so much easier.

Unfortunately, modern software teams don't value documentation and that's the source of a lot of miscommunication, slowdowns and frustration.

[pojzon → luckydata]

"WORKING PRODUCT, over comprehensive documentation"

Software changes too fast to make a static snapshot of it. Its the same with comments in the code, few months later what was there is no longer valid and only creates confusion.

But i can understand managers dont like that because it makes it harder to replace ppl.

[zeroname → pojzon]

> Software changes too fast to make a static snapshot of it.

Architectures don't really change that fast or often, except maybe in the initial phase. That's why most UML diagrams are a waste, they are concerned with low-level details like classes or internal interfaces.

[ako → zeroname]

Agreed, the architecture diagrams I usually look for are high level, mostly about how different systems are connected. These don't change that much.

When looking at architecture diagrams, usually you don't want them lower level details anyway, they would just obscure the big picture.