I've just seen your presentation on OpenSlava 2017. It was really nice and descriptive. I like the approach to treat diagrams as a map with a different level of details on it.
Things which I'll keep in my mind:
always add a legend to a diagram
I hate when people are using acronyms, symbols etc. which can be confusing and/or be interpreted in many of ways
create documentation which could be read in 1-2 hours to get an introduction into project
I agree that 1-2 hours should be enough to catch big picture, and should be enough for reader to know where to look in code for more details.
An extra thought. You said that 1 on 10 people knows UML. I'm just wondering how would a group consisting of 10 people who know UML handle with your exercise with diagram creation and interpretation. Would they be confused or would they read it slightly? It could be very interesting and funny experiment.
Once again thanks for your opinion in this discussion.
Thanks again, I'm glad you found the talk useful. :-)
Yes, I've run my diagramming workshop for teams that have told me they "use UML for everything", and surprisingly the diagrams they produced were the same confused collections of boxes and lines. These diagrams were not particularly UML either, although a few UML notational elements (e.g. interface "lollipops", or the "cup and ball", etc) are often thrown in for good measure. Although I ask groups to use pen and paper, some insist on using electronic tools because they "want to get the UML notation correct". This generally doesn't help either, because you get diagrams like this, which are just meaningless.
In summary, even when I work with teams that "use UML", after some discussion, it turns out that most of them only use class and sequence diagrams, which isn't sufficient for describing software architecture (IMHO, of course). I've seem a very small number of people take a "pure UML" approach to my diagramming workshop, but that tends to make matters worse because nobody else understands the notation being used.
A big problem here is that it's really hard to find a good set of example UML diagrams based upon a real case-study, so everybody's view of UML is wildly different. This again comes back to abstractions. If you can figure out what abstractions (and, therefore, levels of detail) you want to show, the rest falls into place easily. This is why the C4 model exists, and why it's an abstraction-first approach.
I am dearly interested what you think about the AUTOSAR specifications if you mind to take a quick look at them. I'll hold back my opinion on this until I've heard at least one educated judgement from someone else.
I've been pointed to AUTOSAR before, but I don't generally work in the automotive industry, so I'm not sure I can offer much in the way of an opinion about it. I hope there is a good amount of benefit given the specification is 270 pages though. :-)
Some other verticals have their own domain-specific modelling languages too; embedded software immediately springs to mind, where I've seen domain-specific "architecture description languages" used. In my experience, even these teams (and those creating comprehensive documentation for regulatory purposes) are seeking ways to improve their communication. For some, UML is a good fit. For others, not so much.
We're a place where coders share, stay up-to-date and grow their careers.
We strive for transparency and don't collect excess data.