Depends on the target audience. Mostly the audience is hand wavy types that just want to point at a beautiful thing in a slide to point out "we have stuff with icons that you might know! Look at how beautiful this is. It almost looks like we know what we are doing!". Exaggerating here but anything that fits on a single slide is completely useless to an expert. Not worth drawing unless the goal is to impress non experts like that. It's a marketing tool in that case. The level of detail required for this is "a power point slide".
In companies/organizations that are large enough you always get a certain amount of project bureaucracy, ass coverage, and other documentation that doesn't technically do anything more than impress easily impressible types. But it's rarely actually useful. I usually just go straight to the code repositories and ignore things like wikis and other crap. Complete waste of time usually. Show me what you really have. I'll figure it out in no time.
Two mistakes people make with these tools:
1. Spending lots of time using them believing that the output is actually useful/valuable to engineers. Your time is more valuable. You should be doing more productive things. Minimize time you spend on drawing pretty pictures. They didn't hire you for your graphical design skills. This is of course subjective and context dependent. Sometimes it's just required to have diagrams. E.g. operations people like having good documentation just as a way to ensure that they can follow strict processes and make good decisions as to what is in their scope and what needs escalating. There's also a certain amount of impressing the customer, senior management, or other stake holders that "we have stuff". The bigger the company, the bigger the need for project bureaucracy like this. But it is bureaucracy and you want to be efficient with it. Quick and easy.
2. Believing that these are design tools. They are not. They are documentation tools. You use them after you build the thing. Before you build the thing, you use something like a white board. Or pen and paper. A napkin. Anything fast and easy that doesn't slow you down. It's transient stuff and when you start building the thing you'll realize half a dozen topics you did not take into account. So, other than as a record of all the design mistakes you are making, such diagrams have no long term value. You document the solution after you found, solved, implemented, and tested all the design problems. Not before.
Friendly reminder that the places where you are least likely to find diagrams:
- Any kind of large open source project. Or any open source project really. Just not a thing. The bigger and more complicated they are, the less likely it is to have diagrams. Reason: they are redundant and absolutely nobody volunteers to sit down and do them. Just ask yourself: "what would Linus Torvalds say when asked to provide diagrams for the linux kernel". I imagine a fair bit of cursing would happen.
- Especially open source projects that are about producing diagram tools. I personally find this highly ironic. People won't eat their own dog food when the dog food is diagramming tools. Diagramming tools are something you build for others to use. Go look for it on Github if you don't believe it. All you will find is toy examples but nothing actually documenting these tools in any level of detail.
- Small startups or other companies that are highly innovative and have a fast pace of change happening all the time. Reason: people have better things to do than mess around with diagrams. The rainy afternoon where you really have nothing more valuable than messing around with boxes and arrows to do never really happen.
Where do you find people messing around with diagrams? Bloated engineering teams in corporate situations. The more boring the company, the more useless types they employ, the more diagrams you will find. People insisting to each other that "somebody" (not them) should do a diagram. I usually just bounce the question when it comes up. "Great idea, when can you have it done?" Usually the implied suggestion is that I should sit down and waste my time doing a diagram for them that they will never even look at for more than a few seconds. It's write only documentation.
I would have to disagree. If you have a larger system, then onboarding, design discussions, and communicating changes will be more efficient if you have a consistent language and up-to-date conceptual understanding of the system compared to having to perform code archaeology and reverse-engineer the previous maintainer's intent each time you want to change something.
That's what I would call aspirational usage. Ask yourself is your best use as a 200$ and hour senior architect to be writing onboarding documentation?
I've been in plenty of companies with diagrams and universally they were incomplete, not that informative or helpful, typically outdated, and kind of obvious. That's because they are typically rush jobs exactly because the best people that could be doing these diagrams have way more important/urgent/valuable things to do.
In companies/organizations that are large enough you always get a certain amount of project bureaucracy, ass coverage, and other documentation that doesn't technically do anything more than impress easily impressible types. But it's rarely actually useful. I usually just go straight to the code repositories and ignore things like wikis and other crap. Complete waste of time usually. Show me what you really have. I'll figure it out in no time.
Two mistakes people make with these tools:
1. Spending lots of time using them believing that the output is actually useful/valuable to engineers. Your time is more valuable. You should be doing more productive things. Minimize time you spend on drawing pretty pictures. They didn't hire you for your graphical design skills. This is of course subjective and context dependent. Sometimes it's just required to have diagrams. E.g. operations people like having good documentation just as a way to ensure that they can follow strict processes and make good decisions as to what is in their scope and what needs escalating. There's also a certain amount of impressing the customer, senior management, or other stake holders that "we have stuff". The bigger the company, the bigger the need for project bureaucracy like this. But it is bureaucracy and you want to be efficient with it. Quick and easy.
2. Believing that these are design tools. They are not. They are documentation tools. You use them after you build the thing. Before you build the thing, you use something like a white board. Or pen and paper. A napkin. Anything fast and easy that doesn't slow you down. It's transient stuff and when you start building the thing you'll realize half a dozen topics you did not take into account. So, other than as a record of all the design mistakes you are making, such diagrams have no long term value. You document the solution after you found, solved, implemented, and tested all the design problems. Not before.
Friendly reminder that the places where you are least likely to find diagrams:
- Any kind of large open source project. Or any open source project really. Just not a thing. The bigger and more complicated they are, the less likely it is to have diagrams. Reason: they are redundant and absolutely nobody volunteers to sit down and do them. Just ask yourself: "what would Linus Torvalds say when asked to provide diagrams for the linux kernel". I imagine a fair bit of cursing would happen.
- Especially open source projects that are about producing diagram tools. I personally find this highly ironic. People won't eat their own dog food when the dog food is diagramming tools. Diagramming tools are something you build for others to use. Go look for it on Github if you don't believe it. All you will find is toy examples but nothing actually documenting these tools in any level of detail.
- Small startups or other companies that are highly innovative and have a fast pace of change happening all the time. Reason: people have better things to do than mess around with diagrams. The rainy afternoon where you really have nothing more valuable than messing around with boxes and arrows to do never really happen.
Where do you find people messing around with diagrams? Bloated engineering teams in corporate situations. The more boring the company, the more useless types they employ, the more diagrams you will find. People insisting to each other that "somebody" (not them) should do a diagram. I usually just bounce the question when it comes up. "Great idea, when can you have it done?" Usually the implied suggestion is that I should sit down and waste my time doing a diagram for them that they will never even look at for more than a few seconds. It's write only documentation.