[HN Gopher] Architecture diagrams should be code
___________________________________________________________________
Architecture diagrams should be code
Author : todsacerdoti
Score : 54 points
Date : 2023-01-10 08:51 UTC (1 days ago)
(HTM) web link (brianmckenna.org)
(TXT) w3m dump (brianmckenna.org)
| blowski wrote:
| I'm always torn on this topic.
|
| On the one hand, diagrams are easy to update, track changes, and
| show in different contexts.
|
| On the other, a lot of automated diagrams are unclear because
| they miss important aspects of layout.
|
| I believe you should start manual, and switch to code-based when
| it becomes painful to keep updating it.
|
| That said, I don't know why I'd do it in a bespoke system, as
| this article shows. That seems like the worst of both worlds.
| alienreborn wrote:
| In our team, we use https://diagrams.mingrammer.com to create
| architectural or dataflow diagrams in our docs via code.
| T-Winsnes wrote:
| I've often found that diagrams as code is fine for simple things,
| but once the complexities start adding up, it becomes as much
| work maintaining the diagrams as it is to main the actual
| codebase. I honestly think there is little difference in effort
| required to maintain a diagram in something like draw.io over
| PlanetUML or ilograph. Time is just spent in different places
|
| Automatically laying out diagrams in a away that makes contextual
| sense is one of those problems that seems easy, but is actually
| really hard. If it was easy, everyone would have used dot files
| and graphviz to generate their diagrams since the 90s
|
| Disclosure: I'm the CTO at hava.io, where we automate cloud
| environment diagrams, so I'm biased towards automation
| manv1 wrote:
| That's a horrible idea.
|
| The problem is that people are munging architecture, data flow,
| and process into one diagram.
|
| "Marketplace" isn't part of an architecture. "Commerce" isn't an
| architecture part. It's a functional piece.
|
| Revamping how architecture diagrams are made won't fix incorrect
| ways of describing architecture.
| al2o3cr wrote:
| Short summary: "Making diagrams with a GUI didn't feel hard
| enough, so I do it with Haskell instead because Serious Computer
| Science"
| zcmack wrote:
| i rebuked in horror when haskell was mentioned much like i
| rebuke in horror when vizio is mentioned. :)
| groby_b wrote:
| I'd suggest evaluating tools on an as-needed basis, instead
| of wholesale rejection. And I'd 100% agree that the article
| could've benefited from a "Why Haskell, specifically"
| section. But really, few things are unequivocally useless.
| (Or good, for that matter)
|
| (I'd also suggest that you meant 'recoiled', not 'rebuked')
| mattpallissard wrote:
| That wasn't my take away at all.
| aliswe wrote:
| Yes! we introduced mermaid for all our important repos.
| lifeisstillgood wrote:
| 1. Oh god yes. Anything to stop management by powerpoint.
|
| 2. But a piece of code written seperate and distinct from the
| actual code is just as disassociated from the real world.
|
| 3. So build the diagram from the actual code (parse the code in
| the repos, monitor real time network calls, put the data in the
| config files. whatever)
|
| 4. please for the love of god stop using low code solutions -
| they just make another huge hurdle to being able to introspect.
| GenerocUsername wrote:
| I am a solution architect who uses Lucidchart as well as
| automated arch docs like dependency cruiser and plantuml.
|
| They both have value, and I will never give up custom
| diagramming.
|
| It comes down to expression. Not everything in a diagram is
| purely informational, sometimes you need to represent concepts
| and relationships in ways that are very frustrating to encode in
| code
| Veuxdo wrote:
| Here's another argument from last year:
| https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...
|
| As for Haskell... while I think architecture diagrams should be
| written in code, they _shouldn 't_ be written in a programming
| language. Programming languages are for writing, well, programs.
| Programs execute, accept input, have state, and all manner of
| other things that just don't apply to diagrams. Diagramming in a
| programming language is just weird.
| pufuwozu wrote:
| I didn't mention it, but I do write architecture diagrams which
| have input. data Version = Current | Future
| generate :: Version -> Diagram
|
| Implementation uses a few if/else expressions. Really simple.
|
| The final points of the post was that we should be able to
| generate architecture diagrams from other code. Parsing a
| service descriptor, generating them from tests, etc. You DO
| need a programming language.
| Veuxdo wrote:
| Fair point, and an interesting distinction, I think.
| Diagramming _from_ code vs. diagramming _with_ code...
| tarasglek wrote:
| I feel like Jaeger and related tracing tools are basically this.
| I wish opentracing could go beyond rpc and into dbms guts and
| kernel internals.
|
| Instead of looking at semi fictional assumptions of how services
| are tied together, you can follow the actual flow.
| falcolas wrote:
| I love tracing as much as anybody, but that's most useful
| tracking between processes - when you can have boundaries
| within a single process too.
|
| Having both - the diagram of what you expect and the diagram of
| reality - are useful.
| lolsal wrote:
| Architecture documentation is not just consumed by
| programmers/coders. I can't imagine showing Haskell (or something
| similar) to non-technical leadership or during an M&A process.
|
| Know your audience. Frankly I would loath trying to decipher code
| when getting a high-level view of the architecture of a system
| during onboarding.
| Denvercoder9 wrote:
| TFA isn't advocating _consuming_ architecture diagrams as code,
| but _creating_ them with code. Render them and you get back the
| same images as you had before.
| dack wrote:
| he suggested generating plantuml diagrams from it, so you would
| use the image for onboarding. you'd only see the code if you
| were going to update the architecture
| pufuwozu wrote:
| I don't often show architecture diagrams to non technical
| people BUT I also definitely don't show most technical people
| this Haskell code. I also don't show them the PlantUML.
|
| I show them the png image.
| dragonwriter wrote:
| Architecture-as-Code is _source_ code. It can be compiled
| /rendered to other forms, like diagrams. ( _Ideally_ I 'd like
| sonething like CSS to control styling the diagrams in so that
| you could adjust rendering, even selectively hiding pieces that
| aren't interesting to a particular audience, without touching
| the logical description.)
|
| In a _perfect_ world, the architecture description would also
| be part of the "working" source code, interacting with more
| normal program code (and /or IAC) specifying the concrete
| components, and playing a concrete role in building and
| deploying systems, so that the work that goes into architecture
| specs isn't duplicated and the arcuitecture description doesn't
| get out of sync with reality.
| austinjp wrote:
| One reason I prefer diagrams as "code" (by which I mean Mermaid
| or similar) is that they can be checked into version control, and
| changes can be reviewed over time. Unfortunately the diffs become
| less meaningful after significant changes.
|
| Hmm.... outputting an image to highlight changes might be fun to
| hack together. One day :)
| dack wrote:
| architecture diagrams change very infrequently, and are most
| useful in a given context (ie tailored to a particular viewer or
| team). writing actual code to describe them feels like a solution
| in search of a problem.
| pufuwozu wrote:
| Atlassian Marketplace's architecture diagrams change
| constantly. Altassian replaces a core system, we have to
| integrate with a new one, we rewrite or replace a system.
|
| Did you read the part about generating diagrams from different
| things, e.g. service descriptors, service proxies, tests?
| didericis wrote:
| Agree, but I get the temptation if you want to be able to
| rapidly evolve your architecture early on to discover what
| works best.
|
| Removing that extra bit of documentation related friction and
| maintenance that keeps an ill suited architecture around longer
| than it should or drifting from reality would be nice. I have a
| hard time seeing how the complexity or quirks of a diagramming
| tool that could also stay tailored to certain views wouldn't
| become more of maintenance headache than being disciplined
| about manual diagrams.
| Waterluvian wrote:
| Something I love about diagramming with a markup language is that
| you get to wipe your hands clean of tedious alignment and visual
| perfection. If you give me the ability to align and resize and do
| all kinds of cosmetic stuff to my diagrams, I will.
| Scubabear68 wrote:
| I have found arch-diagrams-as-code tools do not allow me the
| freedom to emphasize important architecture bits the way I want
| them to.
|
| My most successful tool for diagramming to date has
| been...Keynote of all things.
|
| Yes, they will get out of date and stale, but they still serve
| the purpose as a communications tool.
| Quarrelsome wrote:
| The industry spent a non-trivial time trying to maintain
| diagramming back in the waterfall days under UML and we really
| struggled to find a decisive solution.
|
| As other posters have mentioned there are serious issues with
| having auto-generated and authoritative architecture diagrams.
| The biggest problems include maintenance burden (did you upgrade
| the diagrams?) and automating layout.
|
| Personally I find the least ugly solution is to just draw some
| low-effort arrows and boxes when you need them and (for the most
| part) discard the diagram once you're done.
| derkoe wrote:
| The C4 model (https://c4model.com/) is great for architecture
| diagrams. You can use different tools to generate them. Here are
| the ones I've been using:
|
| - https://github.com/plantuml-stdlib/C4-PlantUML -
| https://structurizr.com/ (by Simon Brown, the creator of the C4
| model)
| chrsig wrote:
| I've looked at mermaid & planetuml before. structurizr is new
| to me and looks interesting.
|
| PlanetUML has the advantage of gitlab support, iirc -- allowing
| rendering of diagrams in README files. I'd like to see more
| options for that.
|
| edit: interestingly, the author of structurizr (Simon Brown)
| was recently linked in another HN thread.
|
| HN thread - https://news.ycombinator.com/item?id=34338995
|
| YT link - https://www.youtube.com/watch?v=x2-rSnhpw0g
| tunesmith wrote:
| Man, I just was browsing around on Mastodon a couple weeks ago
| and found an architect that said he was using a tool for this
| sort of thing, and it was one I never heard of before and it
| looked like it was good. And now I can't find it again. All I
| remember is that it was text files that had a certain file
| extension of more than three letters.
|
| At any rate, architecture diagrams are drawn in a lot of
| different contexts. I find myself reaching for these tools:
|
| If I'm screen-sharing and want to draw something _really_ quickly
| in a collaborative sense with others, I use Flying Logic. You can
| basically draw this as fast as you talk to each other. You could
| substitute that for any other drawing app that will automatically
| lay out as you draw. It basically runs a Sugiyama-type layered
| algorithm in a loop, and it supports groups and nesting.
| Sometimes I 'll export these drawings into wikis, but it's more
| for a general sense - it's really just labeled boxes and arrows.
|
| If I want to quickly put together something more detailed that
| will again be used only for reference, and not as a living
| document, I'll sketch something up in Excalidraw (free version)
| and export it. It still find it a little too fiddly for drawing
| live with an audience, but it has more flexibility than Flying
| Logic since you can also write text outside of the boxes and
| arrows.
|
| But for stuff that needs to be more official and/or be edited,
| I'm all-in on the diagrams-as-text thing. I just haven't find the
| right tool yet. I feel like mermaid and plantuml are a venn
| diagram and haven't really committed to either. There's also that
| crazy python one that has all the AWS-branded diagram elements
| but it's too finicky to pull up quickly.
| okamiueru wrote:
| PlantUML? Draw.io?
| [deleted]
___________________________________________________________________
(page generated 2023-01-11 23:00 UTC)