Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

Architecture diagrams enable better conversations

unravelled.dev

Post reply on HN
Print view View original

121–130 of 141 posts

Re: Architecture diagrams enable better conversations

#121

Post by bentinata »

SnowProblem wrote: post #119
jhund wrote: post #33

I've been using https://structurizr.com/ to automatically generate C4 diagrams from a model (rather than drawing them by hand). It works well with the approach for written documentation as proposed in https://arc42.org/ . It's very easy to embed a C4 diagram into a markdown document. The result is a set of documents and diagrams under version control that can be rendered using the structurizr documentation server (fo…

Structurizr looks popular but I don't love needing to learn yet another DSL. Does there exist a way to describe things in an existing language with a library? To use the example on their website, I would like something like this in JS: let { Component, Container, Diagram, Person } = import 'c4' let user = new Person('User') let system = new Container('Software System') let webapp = new Component('Web Application') le…

There is also https://diagrams.mingrammer.com/ using python.

Re: Architecture diagrams enable better conversations

#123

Post by rpbiwer2 »

necovek wrote: post #106

I'll go on a limb and share a counter-point for why I struggle with diagrams: it's anecdotal but might help someone else accept that diagrams are not for everyone. As someone with aphantasia, they don't help me memorize relationships, so to get them into my working memory, I have to translate a diagram into bullet points: it's so much easier just to start with those bullet points of what components we've got, what th…

I agree. I don't have aphantasia but most of the time when I look at an architectural diagram it feels like I'm looking at nothing at all.

Re: Architecture diagrams enable better conversations

#124

Post by minhmeoke »

jhund wrote: post #33

I've been using https://structurizr.com/ to automatically generate C4 diagrams from a model (rather than drawing them by hand). It works well with the approach for written documentation as proposed in https://arc42.org/ . It's very easy to embed a C4 diagram into a markdown document. The result is a set of documents and diagrams under version control that can be rendered using the structurizr documentation server (fo…

If you want to create diagrams from textual descriptions, https://kroki.io/ is very versatile and supports several different markup languages including C4.

Alternatively, if you want to stick to ASCII output, https://arthursonzogni.com/Diagon/#Sequence supports several formats (see the dropdown) which can pipe into something like Typogram (https://google.github.io/typograms/) for more beautiful output.

For example, input:

  Renderer -> Browser: BeginNavigation()
  Browser -> Network: URLRequest()
  Browser  Browser: DidCommitNavigation()
will output the following sequence diagram:

  .--------.            .-------.     .-------.
  |Renderer|            |Browser|     |Network|
  '--------'            '-------'     '-------'
      |                     |             |    
      |  BeginNavigation()  |             |    
      |-------------------->|             |    
      |                     |             |    
      |                     |URLRequest() |    
      |                     |------------>|    
      |                     |             |    
      |                     |URLResponse()|    
      |                     ||             |    
  .--------.            .-------.     .-------.
  |Renderer|            |Browser|     |Network|
  '--------'            '-------'     '-------'
and then you can perform further edits using something like https://asciiflow.com/ (web, free) or https://ivanceras.github.io/bob-editor/ (web, free) or https://monodraw.helftone.com/ (Mac only, proprietary) as mentioned in other comments from https://news.ycombinator.com/item?id=37040883.

Re: Architecture diagrams enable better conversations

#125

Post by hollerith »

minhmeoke wrote: post #124
jhund wrote: post #33

I've been using https://structurizr.com/ to automatically generate C4 diagrams from a model (rather than drawing them by hand). It works well with the approach for written documentation as proposed in https://arc42.org/ . It's very easy to embed a C4 diagram into a markdown document. The result is a set of documents and diagrams under version control that can be rendered using the structurizr documentation server (fo…

If you want to create diagrams from textual descriptions, https://kroki.io/ is very versatile and supports several different markup languages including C4. Alternatively, if you want to stick to ASCII output, https://arthursonzogni.com/Diagon/#Sequence supports several formats (see the dropdown) which can pipe into something like Typogram ( https://google.github.io/typograms/ ) for more beautiful output. For example,…

Huh. I find the input more readable than the output.

Re: Architecture diagrams enable better conversations

#126

Post by jtwaleson »

algomammoth wrote: post #79
jtwaleson wrote: post #45

Earlier quoted context omitted.

I’m working on exactly this idea, if it goes well I’ll launch it as a product. I am trying to figure out the value proposition and who to sell it to and for how much. If anyone has ideas, please reach out. I would be very grateful.

I am also working the on a personal project like this in my free time, but would really like to see others' work or even contribute to them. Would you be up for exchanging ideas?

Yes! Email is in my profile.

Re: Architecture diagrams enable better conversations

#127

Post by antonvs »

necovek wrote: post #106

I'll go on a limb and share a counter-point for why I struggle with diagrams: it's anecdotal but might help someone else accept that diagrams are not for everyone. As someone with aphantasia, they don't help me memorize relationships, so to get them into my working memory, I have to translate a diagram into bullet points: it's so much easier just to start with those bullet points of what components we've got, what th…

I’m not sure aphantasia is the issue here. I have aphantasia but I find good architecture diagrams useful, and I regularly draw them. I don’t need to be able to visualize them with my eyes closed to use them - instead, just look at the diagram. They’re intended to be referenced, that’s why they’re useful.

As such, I’m not sure that “memorizing relationships” is their goal. As the OP article says, communication is one goal. But also, drawing a diagram is a lot like writing - it forces you to think about what you’re documenting and often uncovers points that need to be addressed.

Bullet points can’t really capture what a diagram can - you need to represent other relationships in addition to the simple hierarchical structure that bullet point provide. If you use a diagramming tool with a DSL, you’ll see this in the diagram definition - it starts to become difficult to read a non-trivial diagram in textual form, because of relationships between different parts of the text.

I’m not suggesting that you should find diagrams useful, but I think that what you’re looking for from them may not be their main purpose.

Re: Architecture diagrams enable better conversations

#128

Post by knsv »

llanowarelves wrote: post #66
stetrain wrote: post #42

There's some discussion here about linking diagrams to code or vice-versa. And while that's useful for documenting code already written, where I personally have found diagrams to be the most useful is in the planning discussions before and during writing the code in the first place. A room full of people can talk about things for hours without making progress, but as soon as you starting moving boxes and arrows aroun…

They are great because you can find so many problems at much lower cost earlier. And communication across domain and skill levels. Maybe their unpopularity among developers stems from trauma of the UML+OOO+Waterfall days and an overcorrection in the opposite direction. Or many more are doing it and just not talking about it since it's not as exciting as code.

Good point. Finding a middle ground is the way to go. Keeping enough details in the diagrams to keep them useful but without the extra overhead. You cant keep all the details in the diagrams, they belong in the code.

Re: Architecture diagrams enable better conversations

#129

Post by bdg »

vaughan wrote: post #17

Code should generate diagrams automatically as you write it. Then you can see the complexity increase as you go, instead of looking back on a tangled mess.

Our languages mostly do not have the syntax needed to express higher abstractions. You could create one via meta files or special comment notation perhaps, but it doesn't exist yet (outside of class diagram generators).

A big part of this problem is the "code-model gap".

Re: Architecture diagrams enable better conversations

#130

Post by midasz »

FearNotDaniel wrote: post #90
rammy1234 wrote: post #75

Earlier quoted context omitted.

I use MermaidJS for flow chart and Sequence diagram. They have C4 in beta. I tried and it is hard adjust the layout and many features are not supported for C4 yet. Visual Studio has good support for MermaidJS. https://mermaid.js.org/intro/

I think you mean Visual Studio _Code_. Completely separate product. Not your fault of course, but the geniuses at Microsoft who gave the same name to two different IDEs in an environment where users of the second one are very unlikely to be aware of the existence of the first. Still, it's an important distinction worth knowing about because they have their own distinct extension ecosystems that are not mutually compa…

Yeah microsoft really have a knack for naming things
Post reply on HN