Hacker News Reader

Comment by IshKebab | Hacker News Reader

Interesting but I don't think this especially adds anything. The high level diagrams are great but then you can already make those without having to read any fancy visual model websites. The site even kind of admits this:

> As an industry, we do have the Unified Modeling Language (UML), ArchiMate and SysML, but asking whether these provide an effective way to communicate software architecture is often irrelevant because many teams have already thrown them out in favour of much simpler "boxes and lines" diagrams.

This is very true, but then they seem to have ignored the reasons why UML class diagrams were a total failure. They somehow acknowledge that nobody likes them, but then the 4th C of their model (code) is... UML class diagrams!

You don't need this. Just do ad-hoc diagrams and make them clear, with labelled arrows. Their first three diagrams are actually good examples of this.

View on HN

That's what I do. Boxes and lines between them. It helps a lot when thinking up new concepts and brainstorming too, so that the tool doesn't slow you down.

I use Freeform now, which is super simple but works. Mark two objects and cmd-click/right click, then click "add connecting line".

Is it Freeform as the Apple Freeform? I tried it last week to create high Level design, still not as smooth as I expected. Mainly the text editing flow feels not seamless yet, the deal breaker was I couldn't get the file successfully shared thru any available options.

To be fair it's still in its early of its time, I'll wait bit longer.

Apple Freeform yes, comes with macOS. Before that I used Keynote.

One step further: Powerpoint. Sooner or later the diagrams will usually be needed in a presentation. Having them in a presentable format saves another step, and is a constant reminder to produce something worth presenting.

Those diagrams that don't end up in presentations will be write-only anyway, and could be in any random format. No-one is going to read them.

That’s a really good point, I’ve had to redo diagrams before to fit them into a presentation, and because they were sprawling all over the place in Figma or Miro, they required extra work to fit correctly and be readable. Powerpoint or Google Slides forces you to concision and the aspect ratio of the slide, for good or bad.

Freeform is basically a simplified Keynote, which it is based on. I used Keynote before. Might actually return to it since Freeform is pretty basic right now (it's pretty new).

UML is still highly used at the architecture command deck, even if the dream to generate code from diagrams failed.

Just a couple of months ago I finalized yet another archictecture document, with enough class diagrams, sequence diagrams and use cases on it.

Try testing if people can comprehend the diagrams by asking a question after showing them a somewhat complicated one. You'll likely be disappointed. We don't seem to be using them because they work.

As it happens, most people understand easier a standard notation that can refer to, and get a book at the library, than NIH boxes and lines.

Now people straigth out of bootcamps calling themselves engineers, without having a Software Engineer degree, yeah maybe not.

Then again, they can get that book I just mentioned, and in the process maybe discover other goodies at the local library, or just ask ChatGPT.

> As it happens, most people understand easier a standard notation that can refer to, and get a book at the library, than NIH boxes and lines.

I do not believe this for a second. You're possible arguing against a straw man.

The alternative to UML isn't a "NIH UML" which uses a different array of arrows. It's labelled boxes and lines. You don't need to go to a library to understand the diagram because the diagram is self-explanatory.

Here's a really good example:

https://buck2.build/docs/concepts/concept_map/

Every arrow is labelled. No tedious textbook needed.

You are free to believe in whatever makes you happy, I am not UML missionary.

I don't think the standard matters, so much as the visual diagraming not seeming to work well at scale.

A drawing showing the relationships between database tables seems to be comprehendible to people, until you get to over 7 tables or so, and then they don't appear to be able to make sense of it. Real databases often have magnitudes more tables than that.

You apparently have something you can do a trial with. Show it to people, give them time to digest, and politely quiz them a bit to see if it worked.

In practice this doesn't work very well in an enterprise, the boxes end up a mix bag of different levels of things, some abstract some concrete, some just random.

So if you need to piece together larger chunks of architecture, a supply chain for example, you basically have to redo it all. There is a lot of waste in this, and no one has a sufficiently clear view of the overall architecture, which leads to other waste and quality issues.

For some reasons most engineers get very defensive about a more formal approach, I suspect mostly because it doesn't immediately benefit them or they haven't had too deal with large scale architecture and don't see the problem.

Having structured architecture conventions becomes more important when you have many architecture conversations across multiple people and would like to gain insights from the diagrams too.

But you don't need and official standard that everyone learns. Just use words. If your box is a class, write "class Foo". If your arrow means "contains 1 or more" just write that next to the arrow.

Yes, that’s exactly the convention that C4 specifies: add legends on every diagram and make sure things are labeled in a way that people can understand.

Well they don't follow their own rules then because the "Level 4" diagram on that page is just standard awful UML with no legend or labels.

Reply on news.ycombinator.com