There was a recent talk about the model-code gap [1]. How diagrams often don't map to the code. The C4 model. "Structurizr." Lack of common abstractions to describe software, in contrast with other fields like electrical engineering. Good to still start out with paper/whiteboard.
@7:13 "1 out of 10 people use UML," in his experience. People adopt ad hoc notations instead.
His use of UML is not for describing the system at a high level.
[1] GOTO 2016 • Visualise, Document and Explore Your Software Architechture • Simon Brown
The best way to make sure your diagrams map to code, is to generate your diagrams and the code from a common piece of text.
At a job not too long ago, we used a modified form of DOT to describe a protocol state machine. This generated dot, .h's, and some template .c files. This made it such that each state machine for the protocol had a diagram that would map out all the states. Logging and other subsystems output were generated as well so you could go from a log of a test run back to a diagram of what had run.
Code generation (or compilers for compilers) are entirely underrated outside of Lisp, and they're not too difficult to create.
EDIT: And note that your linked presentation is AWESOME, but I think he misses the description / guidebook being up to date is best accomplished by having it be what needs to be updated to create the software.
There was a recent talk about the model-code gap [1]. How diagrams often don't map to the code. The C4 model. "Structurizr." Lack of common abstractions to describe software, in contrast with other fields like electrical engineering. Good to still start out with paper/whiteboard.
@7:13 "1 out of 10 people use UML," in his experience. People adopt ad hoc notations instead.
His use of UML is not for describing the system at a high level.
[1] GOTO 2016 • Visualise, Document and Explore Your Software Architechture • Simon Brown
https://www.youtube.com/watch?v=GM_J_jRp62g