Hacker News Reader

Comment by manbash | Hacker News Reader

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.

View on HN

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/) might provide a better communication model than text.

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...

It does have a very good VS Code plugin providing autocomplete and (somewhat laggy) diagram preview

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

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.

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?

Reply on news.ycombinator.com