4 ms·

I have no use for architecture diagrams. Every diagram I've seen, ever, had the problem that it lacked sufficient detail to be of any use other than saying to n

I have no use for architecture diagrams. Every diagram I've seen, ever, had the problem that it lacked sufficient detail to be of any use other than saying to non technical people "we have stuff, here's a pretty slide for you to prove that". That's literally the only reason I get asked to produce diagrams. A diagram with sufficient detail to be actually of use to people like me would not fit on a slide. And it wouldn't be that useful. Because you'd have to study it to understand how it all fits together. You might as well inspect the real code base and learn way more in about the same time frame. In fact, that's what I do. In the rare case that there are diagrams at all they are extremely unlikely to be of any use whatsoever. And if you are thinking I know nothing about the subject and must obviously be an idiot. I actually did my Ph. D. 20 years ago in this field. I read a lot of books, articles, etc. on this topic. I deeply immersed myself in this stuff. So, my well informed opinion is that software architecture drawings serve no purpose whatsoever. Complete waste of time. Nice talking point on a whiteboard during a meeting. Wipe the board when the meeting ends. Big OSS projects don't have diagrams. Even OSS projects that implement architecture drawing tools. I find that highly ironic. Tool makers that create UML drawing tools don't eat their own dog food. That should tell you all you need to know about such tools.

anonred 4y ago
Do you have any concrete data from your PhD to back up your claims about diagrams being useless, or just personal takes on the subject?
- jillesvangurp 4y ago
  I have a couple of decades of experience with real life projects. None of which featured diagrams in the last 20 or so. From extensive interactions with colleagues and friends I know for a fact that this is the case across the board. I have no counter examples. Maybe I live in a weird bubble where people just don't do these things. You know, companies like Nokia, Here Maps, and a few others. Most of the startups in Berlin, or any of the various companies I've visited in the US over my career. Just not a thing anymore. It was once of course, and unlike most people in this thread I actually did some case studies at companies that proudly showed me their work in the form of lengthy architecture design documents featuring lots of high level and perfectly useless diagrams. That's the reason people don't do this anymore. It's a lot of effort and you don't get a whole lot in return. Doing case studies like this is hard and thankless work BTW. I spend way too much time looking at architecture documents and then learned more about the documented systems by actually talking to the persons that wrote those documents in about 30 minutes. These documents were basically stating the bleedingly obvious and omitting everything else. Anything actually complex or complicated was left out because it would quickly become unwieldy. A person can tell me that there is a database and it has 20 tables. Or they can quickly tell me what their domain is about and I can infer that they probably have database with things called users, addresses, etc. You don't need a diagram for that. And things like model classes are usually pretty straightforward to read. And unlike the diagram they are actually complete, not out of date, and not overly simplified. Diagram tools are still sold of course. But it's a niche market. The exclusive customers for these tools tend to be mid to large sized companies where this is a necessary evil to keep their customers or managers happy. It's a form of ass coverage. A chore where somebody has to sit down and do that. No OSS project I know of, small or large, includes diagrams in their documentation. Not a thing. Never has been. And yes, I did some case studies of those as well back in the day. Much easier than corporate case studies. If you don't believe me, try finding some diagrams on Github. I'm sure you might find some but I doubt you'll be very impressed. I've seen plenty of engineers ask for diagrams but always in this form "someone (not me, obviously) should do a diagram to make my life easier". It's write only documentation. Outdated almost immediately, and typically rarely looked at. Skip it if you can, minimize your time spent on it if you can't. You have better things to do. Software architect is no longer job title that is common or fasionable. Empirical research in the software world is like architecture diagrams. Lots of people asking for it, not a whole lot of people doing empirical research. And lots of people confusing marketing material with proper research (e.g. most articles published on Agile methodology). And even fewer researchers that even do a half decent job when they do it. It's hard and typically not covered in computer science degrees. So there are a lot of not so skilled, amateur empirical researchers doing a not so great job of doing empirical research. And of course companies don't actually like their dirty laundry being published. I know this because I was such an amateur researcher and I read a lot of papers back in the day. Like thousands. Part of the job. Most of those papers were entirely unremarkable. The better ones exceedingly dull reading material with inevitably very unremarkable/predictable conclusions backed up by really impressive research methodology, statistics, etc. The reason I left academia was that I realized that I was not a great empirical researcher, was probably never going to become one, and did not know a whole lot about software engineering and architecture either because I had never worked outside of a university. That's 2 decades ago. Thanks for asking.
yokoprime 4y ago
As someone who are involved half a dozen projects, high level architecture diagrams are extremely useful. This is especially true when meeting with stakeholders in other teams and explaining what we need to do to accommodate their requests, and also when onboarding new resources. The way I use diagrams, they should not be code as that is just added complexity without any benefit
mjevans 4y ago
Some diagrams work better as posters or even whole walls, so that it's easier for a human to move across the project and see everything on one huge map that works at an intuitive zoom level.
bottled_poe 4y ago
Ridiculous. Diagrams are extremely useful for communicating the essential information efficiently. Not everyone needs to spend time going through every line of source code to understand design concepts. I’m really struggling to see how this could possibly be argued otherwise.
kortilla 4y ago
Cool anecdote. Mine is that they have been useful in nearly every systems design I’ve been a part of early on. You don’t think visually/spatially, some people do. Putting boxes with lines clearly groups responsibilities and defines which pieces are related. It’s the same reason org charts exist. It doesn’t tell you how a company functions but it very quickly tells you who answers to who.
tsimionescu 4y ago
I don't know where you get this from, but in my experience, high-level architecture diagrams are excellent at ramping up someone new on a team. They help immensely in giving them a map to what the code represents, and they are likely to refer back to the diagram often when crossing module boundaries. The whole value of diagrams is that they don't have as much detail as the code. They can thus focus on the intent and on the bigger picture of how things are organized, instead of getting trapped in the weeds of machine details. OSS projects are also not exactly famous for their well-considered documentation and on-boarding tools. It would be like concluding QA is useless because big OSS projects usually lack QA engineers and test plans.
deleted 4y ago
[deleted]
aaron695 4y ago
[dead]

anonred 4y ago

Do you have any concrete data from your PhD to back up your claims about diagrams being useless, or just personal takes on the subject?

jillesvangurp 4y ago
I have a couple of decades of experience with real life projects. None of which featured diagrams in the last 20 or so. From extensive interactions with colleagues and friends I know for a fact that this is the case across the board. I have no counter examples. Maybe I live in a weird bubble where people just don't do these things. You know, companies like Nokia, Here Maps, and a few others. Most of the startups in Berlin, or any of the various companies I've visited in the US over my career. Just not a thing anymore. It was once of course, and unlike most people in this thread I actually did some case studies at companies that proudly showed me their work in the form of lengthy architecture design documents featuring lots of high level and perfectly useless diagrams. That's the reason people don't do this anymore. It's a lot of effort and you don't get a whole lot in return. Doing case studies like this is hard and thankless work BTW. I spend way too much time looking at architecture documents and then learned more about the documented systems by actually talking to the persons that wrote those documents in about 30 minutes. These documents were basically stating the bleedingly obvious and omitting everything else. Anything actually complex or complicated was left out because it would quickly become unwieldy. A person can tell me that there is a database and it has 20 tables. Or they can quickly tell me what their domain is about and I can infer that they probably have database with things called users, addresses, etc. You don't need a diagram for that. And things like model classes are usually pretty straightforward to read. And unlike the diagram they are actually complete, not out of date, and not overly simplified. Diagram tools are still sold of course. But it's a niche market. The exclusive customers for these tools tend to be mid to large sized companies where this is a necessary evil to keep their customers or managers happy. It's a form of ass coverage. A chore where somebody has to sit down and do that. No OSS project I know of, small or large, includes diagrams in their documentation. Not a thing. Never has been. And yes, I did some case studies of those as well back in the day. Much easier than corporate case studies. If you don't believe me, try finding some diagrams on Github. I'm sure you might find some but I doubt you'll be very impressed. I've seen plenty of engineers ask for diagrams but always in this form "someone (not me, obviously) should do a diagram to make my life easier". It's write only documentation. Outdated almost immediately, and typically rarely looked at. Skip it if you can, minimize your time spent on it if you can't. You have better things to do. Software architect is no longer job title that is common or fasionable. Empirical research in the software world is like architecture diagrams. Lots of people asking for it, not a whole lot of people doing empirical research. And lots of people confusing marketing material with proper research (e.g. most articles published on Agile methodology). And even fewer researchers that even do a half decent job when they do it. It's hard and typically not covered in computer science degrees. So there are a lot of not so skilled, amateur empirical researchers doing a not so great job of doing empirical research. And of course companies don't actually like their dirty laundry being published. I know this because I was such an amateur researcher and I read a lot of papers back in the day. Like thousands. Part of the job. Most of those papers were entirely unremarkable. The better ones exceedingly dull reading material with inevitably very unremarkable/predictable conclusions backed up by really impressive research methodology, statistics, etc. The reason I left academia was that I realized that I was not a great empirical researcher, was probably never going to become one, and did not know a whole lot about software engineering and architecture either because I had never worked outside of a university. That's 2 decades ago. Thanks for asking.

yokoprime 4y ago

As someone who are involved half a dozen projects, high level architecture diagrams are extremely useful. This is especially true when meeting with stakeholders in other teams and explaining what we need to do to accommodate their requests, and also when onboarding new resources. The way I use diagrams, they should not be code as that is just added complexity without any benefit

mjevans 4y ago

Some diagrams work better as posters or even whole walls, so that it's easier for a human to move across the project and see everything on one huge map that works at an intuitive zoom level.

bottled_poe 4y ago

Ridiculous. Diagrams are extremely useful for communicating the essential information efficiently. Not everyone needs to spend time going through every line of source code to understand design concepts. I’m really struggling to see how this could possibly be argued otherwise.

kortilla 4y ago

Cool anecdote. Mine is that they have been useful in nearly every systems design I’ve been a part of early on. You don’t think visually/spatially, some people do. Putting boxes with lines clearly groups responsibilities and defines which pieces are related. It’s the same reason org charts exist. It doesn’t tell you how a company functions but it very quickly tells you who answers to who.

tsimionescu 4y ago

I don't know where you get this from, but in my experience, high-level architecture diagrams are excellent at ramping up someone new on a team. They help immensely in giving them a map to what the code represents, and they are likely to refer back to the diagram often when crossing module boundaries. The whole value of diagrams is that they don't have as much detail as the code. They can thus focus on the intent and on the bigger picture of how things are organized, instead of getting trapped in the weeds of machine details. OSS projects are also not exactly famous for their well-considered documentation and on-boarding tools. It would be like concluding QA is useless because big OSS projects usually lack QA engineers and test plans.

deleted 4y ago

[deleted]

aaron695 4y ago

[dead]