Comment by raphman

10 hours ago

My personal opinion (based in part on HN):

- In a nutshell: everyone should know about UML and how some relevant diagram types look. Nobody should use it religiously.

- Diagrams are great tools for communicating ideas and implementations on an abstract level, and for interactively thinking about ideas that can be drawn in some way. A diagram can also visually highlight problem areas (e.g., components with many dependencies).

- Good use cases for diagrams in SE are e.g., explaining high-level architecture to someone, thinking about and refining database schemas, documenting interaction flows, or giving an overview of class structure in automatically generated code documentation

- It is nice to have visual consistency - it makes parsing a diagram so much faster and less error-prone. UML provides sensible guidelines or inspiration on how to draw e.g., a sequence diagram or a class diagram. There is no need to re-invent the wheel.

- In most cases, knowing about the diagram types and their approximate design is enough. As probably very few people know what the different styles of arrows or boxes might mean, it is a good idea to annotate important elements with their meaning.

- For thinking/communication, drawing diagrams by hand is the best way. Excalidraw/tldraw are nice for stuff that should go into static documents.

- Documenting the state of a system with manually generated diagrams is tedious and requires constant updates. A better way is to auto-generate e.g., class diagrams using PlantUML or Mermaid.