[HN Gopher] Ask HN: Guidelines for making clear architecture dia...
       ___________________________________________________________________
        
       Ask HN: Guidelines for making clear architecture diagrams
        
       I'm new to making software diagrams. I come from a mechanical
       engineering background, and when drawing free body diagrams there
       is a set of conventions commonly followed to make a clear diagram.
       Is there such a set of conventions for software architecture
       diagrams? I googled briefly, but seem to be getting low quality
       articles, most of which are pushing a product :(
        
       Author : pinkmuffinere
       Score  : 10 points
       Date   : 2024-05-01 18:02 UTC (4 hours ago)
        
       | warrenm wrote:
       | ~25 years ago ... I would have UML or, more classically, an ERD
       | or even a flow chart
       | 
       | The only diagrams I have seen in the last decade or two, though,
       | have been Visio (or a similar tool) meant to explain the
       | product's functionality (including where and how it scales) to
       | customers, PS folks, etc
        
       | glawre wrote:
       | I like the C4 Model as a guide on the different levels of
       | abstraction that you might need for your system.
        
         | pinkmuffinere wrote:
         | Oh thanks, this looks like the kind of thing I was searching
         | for -- will read up on it
        
         | NomDePlum wrote:
         | Second this.
         | 
         | Reference for anyone looking I to it: https://c4model.com/
         | 
         | There is also quite a lot of options for helping create these
         | diagrams. I've found https://structurizr.com/ to be the best of
         | what I've tried so far.
        
           | Onawa wrote:
           | I like the idea behind structurizr, but I found the syntax to
           | be too constraining and the tooling around it to be difficult
           | to deal with. That was 2 years ago though,maybe I should
           | revisit it.
        
       | Onawa wrote:
       | As far as guidelines, I have spent time looking as well an never
       | came away with a good answer. One useful website for comparing
       | some of the best tools is https://text-to-diagram.com/. My
       | personal favorite is D2. Still lacking a few layout features that
       | I want, but it gets me 90% of the way there. The syntax is great
       | for projects big to small, and it strikes the perfect balance
       | between "create a diagram fast" and "feature rich". But in terms
       | of actual guidelines, I would agree with another user that C4
       | actually tries to lay out some sort of guidelines.
        
       | contingencies wrote:
       | Conventions exist but they're mostly crap (eg. UML).
       | 
       | Along the KISS principle, boxed elements with connecting lines
       | are the best (simplest, most universally understood, least
       | amgbiguous). In mathematical terms they are an 'undirected
       | graph', a 'directed graph' is the same but with directionality
       | ("arrows") on the links between nodes.
       | https://en.wikipedia.org/wiki/Graph_(discrete_mathematics) The
       | standard toolkit since at least 1991 for defining these in
       | software is https://graphviz.org/
       | 
       | If you need to show the interaction between elements over time in
       | a distributed or complex system, the standard is the message
       | sequence chart
       | https://en.wikipedia.org/wiki/Message_sequence_chart. The best
       | (ie. most long term stable) tool for this be
       | https://www.mcternan.me.uk/mscgen/ which is graphviz-inspired.
       | 
       | There are a plethora of latter-day derivatives such as web-native
       | versions, stylized versions, etc. but these are all functionally
       | irrelevant if you want to be clear, portable and maintainable.
       | Lists of them are frequently posted to HN. The basic workflow is
       | "want to communicate something", "define in text" (which can be
       | done by code), "have image generated", optionally go back and
       | refine.
       | 
       | <neckbeard-yells-at-cloud>The core problem with using web based
       | services, as less experienced / more youthful respondents will
       | suggest, is that they appear and disappear like the javascript
       | frameworks they tend to be built on and thus are a poor match for
       | nontrivial projects with potential medium to long term
       | maintenance and availability requirements. The core problem with
       | Visio and Visio-inspired solutions is that they are WIMP based
       | and thus tend to require manual clicking and placement which is
       | tedious at best and totally unsuited to automated
       | requirements.</neckbeard-yells-at-cloud>
       | 
       | There are also advanced features of these tools which can create
       | complex diagrams like tabular protocol structure diagrams or
       | database structure diagrams, clickable versions, color
       | highlights, and SVG interactive diagrams.
        
       ___________________________________________________________________
       (page generated 2024-05-01 23:01 UTC)