4 ms·

I wish that the lessons from UML would one day lead to the a less ambitious modeling toolkit. What we need are ways to _communicate_ our design, not automate it

I wish that the lessons from UML would one day lead to the a less ambitious modeling toolkit. What we need are ways to _communicate_ our design, not automate it. While comments in code/tests, README.md etc. are a good way to explain the bits and pieces of our software, companies have various stakeholders (software engineers included) that can't affored the time to translate these primitive documentation formats so that they make sense. Visual representation works the best, and I wish that UML would be elaborated as a sketching mean to communicate better with stakeholders, rather than being a part of an ambitious software-generation ecosystem.

draazon 4y ago
There's a place for UML in the README.md; as some other commenters have pointed out, UML works much better as a sketching tool than as a total definition of a software system. A couple of quick class diagrams at the top level (probably generated using something like https://plantuml.com/ https://plantuml.com/) might provide a better communication model than text.
- manbash 4y ago
  Yes plantuml is still my go-to visual design tool, whenever I feel information is missing, and I actually prefer it over mermaid (which has been integrated in github markdown), which I found very lacking. What I like about text-based tools like plantuml/mermaid is the ability to see diffs in PR. Other industry modeling tool use binary databases to represent the UML model and make it harder (i.e. need to use their specific diff visualizers, if available) to review changes of the design. Maybe plantuml should be adopted and maintained. Unfortunately it is still stuck in a Java implementation...
  - bbkane 4y ago
    It does have a very good VS Code plugin providing autocomplete and (somewhat laggy) diagram preview
nottorp 4y ago
That would help but don't call it UML 3. No one will go near it then. IMO any kind of informal diagram helps. Even just some boxes with lines between them.
zozbot234 4y ago
You can still use UML for sketching. The free Doxygen tool even supports reverse engineering of UML class diagrams from (possibly annotated) source code.
NonNefarious 4y ago
On a side note: Why are there almost no VIEWERS for Markdown? Every project has a readme.md, which everyone ends up reading in a text viewer with all the formatting markers all over the place. WTF?

draazon 4y ago

There's a place for UML in the README.md; as some other commenters have pointed out, UML works much better as a sketching tool than as a total definition of a software system. A couple of quick class diagrams at the top level (probably generated using something like https://plantuml.com/ https://plantuml.com/) might provide a better communication model than text.

manbash 4y ago
Yes plantuml is still my go-to visual design tool, whenever I feel information is missing, and I actually prefer it over mermaid (which has been integrated in github markdown), which I found very lacking. What I like about text-based tools like plantuml/mermaid is the ability to see diffs in PR. Other industry modeling tool use binary databases to represent the UML model and make it harder (i.e. need to use their specific diff visualizers, if available) to review changes of the design. Maybe plantuml should be adopted and maintained. Unfortunately it is still stuck in a Java implementation...
- bbkane 4y ago
  It does have a very good VS Code plugin providing autocomplete and (somewhat laggy) diagram preview

nottorp 4y ago

That would help but don't call it UML 3. No one will go near it then. IMO any kind of informal diagram helps. Even just some boxes with lines between them.

zozbot234 4y ago

You can still use UML for sketching. The free Doxygen tool even supports reverse engineering of UML class diagrams from (possibly annotated) source code.

NonNefarious 4y ago

On a side note: Why are there almost no VIEWERS for Markdown? Every project has a readme.md, which everyone ends up reading in a text viewer with all the formatting markers all over the place. WTF?