16 ms·
How to draw software architecture diagrams (2022)
- gnuser 3y agoI highly suggest those interested in this topic check out the blockdiag group of applications (blockdiag, nwdiag, seqdiag, rackdiag) Its been a year or so since I last did an eval of all the options and I keep returning to them. I prefer to have git post-recieve hooks that auto rebuild the images on commit. I liked mermaid but found some major limitations but the brilliantly named python "diagrams" is something I use sometimes as well. With all the font/image improvements you can use on both you can get some very nice stuff going.
- peteradio 3y agoDiagrams should generate themselves. Is there a good markup that does this well? I hate manually manipulating boxes and arrows, can't be assed.
- bobobob420 3y agoI am really jealous of few people I know who intuitely draw amazing diagrams. Some of them are not even good engineers but can draw great looking diagrams. For me its a constant practice to get better and better but I still get amazed when I see high quality diagrams. Visual aesthetics are all around underrated, good diagrams are just so pleasing to look at.
- rperez333 3y agoWhat would be a good library /tool to auto arrange a complex graph (DAG) like the Blender/Unreal/Houdini node interfaces? I would expect some options to set constraints, like the first input staying always aligned with the previous node. Here is one of these DAGs: https://cdnb.artstation.com/p/assets/images/images/026/099/251/large/ryan-gold-tree-gen-nodes.jpg?1587875519 https://cdnb.artstation.com/p/assets/images/images/026/099/2...
- IshKebab 3y agoGraphviz is the classic option but unfortunately it isn't very good. I mean it was great when it was written in the 80s or whatever but then it seems like it was declared "done" and is still stuck in the 80s. Quite annoying because it totally dominates the mindshare of graph layout tools, making it difficult to find alternatives. Here's some other options anyway: * Eclipse Layout Kernel: https://github.com/eclipse/elk https://github.com/eclipse/elk * OGDF: https://ogdf.uos.de/ https://ogdf.uos.de/ In fairness both their websites are pretty terrible (would some examples kill you OGDF?) and they don't provide an easy way to try them out, so I guess it's not that surprising that Graphviz dominates. Anyway in practice if you have a complex graph then doing it manually is by far the best option. If it's too big to do manually then it's unlikely to be a useful graph in the first place.
- danielvaughn 3y agoThe aesthetics of those diagrams strongly remind me of whimsical: https://whimsical.com https://whimsical.com
- exabrial 3y agoThere was once a specification for diagrams called UML. It got laughed out of existence by the egos of developers unfortunately with the dawning of Agile. I believe Dilbert had a comic about it...
- nkozyra 3y agoThere's nothing really wrong about UML, but I find that its association with legacy software development kind of hurts it more than its actual spec and intent. I think the biggest thing a diagram should show you is the way data can and cannot flow. People tend to overcomplicate them with detail that's better suited for a corresponding text document. It's a visual, it should convey things quickly and without much noise.
- dingi 3y agoAlthough I've never heard of D2 until now, it seems like too much programming for a diagramming language. I've used PlantUML for diagramming since couple years and it seems good enough. You need to learn their DSL but you don't have to manipulate visual entities manually.
- WillAdams 3y agoEvery time diagramming comes up in this context, I want to ask the question: >What does an algorithm look like? Why isn't it possible to represent a program visually? Why do complex efforts along these lines either evolve to: https://blueprintsfromhell.tumblr.com/ https://blueprintsfromhell.tumblr.com/ or https://scriptsofanotherdimension.tumblr.com/ https://scriptsofanotherdimension.tumblr.com/ or devolve to nothing more than labeled boxes and a wall of text not markedly more intelligible than the textual program source itself?
- emmanueloga_ 3y agoMy feeling is that the problem is trying to represent the entire program space in a single diagram. I suspect the solution is to slice the representation by meaningful aspects. For instance, if you have boxes and arrows, maybe just focus in a single box, its inputs and its outputs. This is how it's done for electronics circuits, for instance: you don't need to understand everything about the internal components of, say, a 555 ic, just some model of how it works. I also think of blueprints, where projections of the 3d object are displayed together with the object.
- poorlyknit 3y ago> Why isn't it possible to represent a program visually? I'd argue that the visual representation necessarily needs to abstract from the actual code to be useful. From concrete to abstract you can choose from any number of notations, e.g. - Control Flow Graph - Data Flow Graph - Jackson Notation - State Diagram etc. etc.
- WillAdams 3y agoYes, unless you're a visually oriented person like myself who is trying to do the programming visually. I use: https://github.com/derkork/openscad-graph-editor https://github.com/derkork/openscad-graph-editor to try to design woodworking projects: https://forum.makerforums.info/t/openscad-and-python-looking-to-finally-be-resolved/88171/41 https://forum.makerforums.info/t/openscad-and-python-looking... and I'd like to think that I'm managing to keep the visual appearance sufficiently expressive that it is easier to work with than a traditional textual code representation --- jury is still out on that, we'll see when I start re-purposing what I'm working on for odd/even sides, and then then doing the horizontal version of the joinery.
- pimlottc 3y agoThese are generally good tips for visual balance and legibility, but also keep in mind that the main purpose of a diagram is to promote understanding. Visual qualities like symmetry, alignment, relative shape and size imply relationships between nodes, like whether two systems have similar roles, capacity or importance. In one of their examples, there's an "unplanned" node that's placed awkwardly on far side; but maybe that's actually helpful to know! Maybe it's an ugly hack and should stay over there until it's better integrated into the core design. So just make sure the diagram is helpful and accurate first and foremost, then worry about tidying things up. And maybe leave some of the imperfect parts looking a bit more imperfect...
- artur_makly 3y agoWe're about to launch v1.0 of https://VisualFlows.io https://VisualFlows.io Within just few minutes, I was able to design this animated "architectural" map [0]of our parent SaaS. [0] https://app.visualsitemaps.com/user_flows/share/e64da8ed-2efb-4b82-bc44-64a0ba5db32e?s=eyJ6b29tIjoxLjA3NjE1ODg2Nzk3NTIxMzQsInBvc2l0aW9uIjpbNDcyLjUwNTEwOTc1MjI4NjcsMzM4LjcxMDQ2NDE1NzQ5ODM0XX0= https://app.visualsitemaps.com/user_flows/share/e64da8ed-2ef... Notable features include: - Smart Sections[1] - Smart Edges - Smart Node Deletion - Dark/Light modes - Embeddable - Drag n Drop images/svgs/gifs - AWS/Windows/Google Icons -- Markdown(*next week) [1]https://support.visualsitemaps.com/en/articles/6477269-how-to-use-flows#:~:text=coming%20in%20v2.-,Smart,-Sections https://support.visualsitemaps.com/en/articles/6477269-how-t...
- stuartjohnson12 3y agoWhy should I use this over the more mature https://whimsical.com https://whimsical.com that has the same aesthetic?
- blah_why_not 3y ago[dead]
- fijiaarone 3y agoThe article is correct in its esthetics but all it does is highlight the problem of how bad diagramming tools still are — and that they are so bad that a cell phone photo of a smudged whiteboard drawing with horrible handwriting is still preferable, but of course, also uneditable.
- _andrei_ 3y agoFor anyone who likes excalidraw & tldraw, there's this wrapper that handles local storage: https://github.com/revezone/revezone https://github.com/revezone/revezone
- _andrei_ 3y agoCurated list of solutions: - excalidraw - https://github.com/alswl/excalidraw-collaboration - revezone - excalidraw + tldraw - https://github.com/revezone/revezone - code2flow - code - https://app.code2flow.com - zenuml - code - https://app.zenuml.com - bpmn sketch miner - https://www.bpmn-sketch-miner.ai/examples/syntax-0-00-overview.html - d2lang - https://play.d2lang.com - mermaid - https://mermaid.live - diagram.codes - https://www.diagram.codes - kroki - https://kroki.io - nomnoml - https://www.nomnoml.com - azimutt - db, paid - https://azimutt.app - drakon - https://drakonhub.com/try-me - svgbob - https://ivanceras.github.io/svgbob-editor - typograms - https://code.sgo.to/typograms - argdown - for argumentation - https://argdown.org - flowchart.fun - paid - https://flowchart.fun - penrose - advanced, general - https://penrose.cs.cmu.edu - structurizr - https://structurizr.com/dsl - state machine cat - https://state-machine-cat.js.org - drawthe - http://go.drawthe.net - swimlanes.io - https://swimlanes.io - js-sequence-diagrams - https://bramp.github.io/js-sequence-diagrams - dbdiagram.io - https://dbdiagram.io/d - quickdbdiagrams.com - https://app.quickdatabasediagrams.com - edotor - https://edotor.net - pikchr - https://pikchr.org Did some research, I'm working on my own diagramming solution for software design.
- ciceryadam 3y agoI quite like https://diagrams.mingrammer.com/ https://diagrams.mingrammer.com/
- glitchc 3y agoIt's always bugged me that large language models are possible, and yet no one can write a locally available tool that can reflow blocks and arrows to achieve aesthetic beauty. Omnigraffle comes close, but there's nothing available on Linux and Windows is still stuck with Visio. Now I know folks are going to suggest programmable interfaces like GraphViz and Plantuml, but those are not the same thing. Why can't there be a tool where I just draw the boxes and arrows, and the tool aligns everything to make it look pretty?
- ygra 3y agoI'm biased here, but have you taken a look at yEd [π] (or yEd Live [7] for something that runs in a browser) In general however, graph drawing is a set of not that trivial problems to solve. There are a handful of layout styles out there that can, depending on the tool, be configured more or less well. But many of them are fairly specific to graphs with a certain structure. [π] https://www.yworks.com/products/yed https://www.yworks.com/products/yed [7] https://www.yworks.com/yed-live/ https://www.yworks.com/yed-live/
- rakkhi 3y agoAwesome thank you. Added D2 lang to my blog post on this topic: https://open.substack.com/pub/rakkhi/p/cyber-security-design-as-code?r=1afqp&utm_campaign=post&utm_medium=web https://open.substack.com/pub/rakkhi/p/cyber-security-design...
- hyperman1 3y agoI use yEd for drawing this kind of thing. It allows me to make a horribble mess of boxes and arrows, then auto-cleans it up with a few clicks in the menu. It requires making sone compromises, however: Box inside box does not always end well. It is a worthy tradeoff for me, as I can document things much faster, and you get a feel about what will or wont work after a few tries.
- w10-1 3y agoditto. There's no reason to draw anything. Extract relations as tgf (trivial graph format), import, hierarchical layout. tgf: from, to, relation ...
- lstamour 3y agoI use OmniGraffle for similar reasons :)
- walterbell 3y agoIs yEd free to use? The underlying yWorks SDK seems to cost 5 figures for one developer working on one web site. It must be very capable to have customers for ~20 years.
- hyperman1 3y agoTheir page states it is freely available. I cant seem to find the license on their website, unfortunately. I believe it started out as a demo for their paid library, but turned out to be a good standalone application. https://www.yworks.com/products/yed https://www.yworks.com/products/yed
- ygra 3y agoYes, yEd is free to use. The licensing cost you found is indeed for the SDK yEd is built with.
- forward-slashed 3y agoWhimsical is the obvious choice for me to draw diagrams. Well-designed, beautiful, and ergonomic. I also hear Scapple is good. Everything else is overengineered ime.
- viraptor 3y agoIt's weird that the Whimsical diagrams don't look... whimsical. I've started using the sketch style on my draw.io and sketchwow diagrams and that magically makes them more engaging somehow. I'm not sure where the difference comes from, but just clicking that checkbox results in comments about both the contents and the style. (Where otherwise I can't tell if anyone's even read them)
- smokel 3y agoInstead of a "DO NOT ERASE" sign we have introduced a system where you can simply draw a lock icon somewhere on the whiteboard. Only few colleagues know about this arrangement, and even I myself often erase a lot of stuff before I spot that icon.
- bluGill 3y agoMy company has a policy to erase all whiteboards on Friday nights. Nobody tries to steal whiteboard space from the next meetings, and there are no obsolete diagrams from 2018 around with a do not erase.
- tanepiper 3y agoWe use Miro and actually, for high-level stuff, ideation, etc it's pretty good as a tool using post-it notes. I don't go past mid-level stuff though, once you have your components and systems there are better tools for the job.
- sampo 3y agoHere is how to do it with Gimp: http://hackles.org/cgi-bin/archives.pl?request=9 http://hackles.org/cgi-bin/archives.pl?request=9 http://hackles.org/cgi-bin/archives.pl?request=10 http://hackles.org/cgi-bin/archives.pl?request=10 http://hackles.org/cgi-bin/archives.pl?request=11 http://hackles.org/cgi-bin/archives.pl?request=11
- walterbell 3y agoReminiscent of Bret Victor's visualization of live coding, this D2 OSS demo incrementally visualizes a database from SQL statements, generating SVG+text: https://terrastruct.com/blog/post/generate-diagrams-programmatically/ https://terrastruct.com/blog/post/generate-diagrams-programm...
- Veuxdo 3y agoWell it is the same company blog
- walterbell 3y ago2012 Bret Victor video ("Inventing on Principle", https://www.youtube.com/watch?v=PUv66718DII https://www.youtube.com/watch?v=PUv66718DII) preceded D2 by ten years.
- genericlogic 3y agoI really enjoyed this article. When I draw an architecture diagram, write documentation, code or really do anything at work I take a moment to try to make it look "nice". I can't explain why I do it, I just know when I look at it I like it more. I've always been slightly concerned it was possibly not the best use of time, but I have never had anyone tell me not to do it. What I like about the article is that it articulates, in a practical way, how to make something more beautiful, whereas I go by feel. Thanks for sharing.
- dtjb 3y agoEven if you never share anything, just the thought process that goes into the ordering of the blocks and elements on the page force you to think about the larger structure and dependencies. It's incredibly helpful.
- esafak 3y agoThat's what markup is for; it saves you from unproductive embellishment. Obviously, this does not apply for coding.
- growingkittens 3y agoTaking the time to clean up a diagram usually means making it 'easier to comprehend.' Every time you use the clean diagram, you've saved time and energy with a reduced cognitive load.
- walterbell 3y ago> Discussions gravitate around this diagram. People randomly walk up and stare at it. Questions are answered by pointing at it. Periodically throughout the day, chairs swivel around to face this centerpiece, their occupants folding their hands behind their heads. Visualization goals!
- hhjinks 3y agoI do this, too. Coding is actually a very visual endeavour for me. I can only describe it as "flow". If my code doesn't "flow", I'm not happy with it. I am baffled by my teammates who seem to have no visual awareness of their code. They might forego whitespace between the close of one function and the declaration of the next, or alternate between having one or more parameters per line in a function signature. It sticks out to me like a sore thumb, but they don't seem to care.
- victorbjorklund 3y agoI been enjoying D2 lang for creating diagrams. It is like mermaid.js but more formatting options and, imo, better syntax. I wrote a small blog post about it: https://victorbjorklund.com/build-diagrams-as-code-with-d2-d2lang https://victorbjorklund.com/build-diagrams-as-code-with-d2-d...
- nkozyra 3y agoI feel like diagrams should not be pretty. For example, colors should convey meaning rather than being aesthetic or artistic choices. I get that ugly software diagrams are not fun to look at, but to me dressing them up is like adding curves to a line chart - yes it's visually appealing but it interferes with the data being conveyed.
- bluGill 3y agoBeauty is useful, but it needs to be the last step. When something like nice people also assume the contents have been polished and so since a lot of work went into thinking about it already it isn't worth the time to question if it is right. You can question if you understand it, but the diagram itself is right and so the problem is you. Most diagrams have not had that must thought put into them. They should look a little ugly because that implies it might not be right so look for errors.
- nkozyra 3y ago> They should look a little ugly because that implies it might not be right so look for errors. Weirdly, prettiness is the bigger red flag for me wrt to error. I see that and feel like more attention was put into that than the underlying information. Ugly, brutalistic, utilitarian stuff tends to imply a focus on correctness to me.
- Chris_Newton 3y agoNicely presented data can certainly inspire confidence, which might or might not be justified, but I think attractive presentation can be more than just a sales pitch. Ultimately, we create these visualisations to convey information to someone else, so good presentation should help that someone to navigate and understand that information, and it should avoid introducing unwanted bias or ambiguity. If that means creating an overview of the system architecture for new team members that uses pretty colours and multiple fonts and icons and shaded boxes but that helps them to understand the system more quickly and correctly than an overwhelming page of black-and-white text and arrows, the extra styling has done its job.
- Anduia 3y agoIn case you didn't already, if your project is documented with markdown, add ```plantuml blocks to insert your diagrams instead of separate binaries. In Gitlab they are rendered nicely when visiting the .md file with the web browser. Github doesn't have that functionality yet.
- jalk 3y agoGitHub uses mermaid https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/creating-diagrams https://docs.github.com/en/get-started/writing-on-github/wor...
- livrem 3y agoFossil has built-in pikchr-rendering in Markdown (and on Wiki pages) that use the same method (but ```pikchr instead, unsurprisingly): https://pikchr.org/home/doc/trunk/doc/usepikchr.md https://pikchr.org/home/doc/trunk/doc/usepikchr.md
- vishnudeva 3y agoMermaid and C4 Model gang assemble!
- esafak 3y agoIf only I could figure out how to handle branching in Mermaid like the ones after the "Saving" and "Sharing" labels in this animation: https://whimsical.com/ https://whimsical.com/
- hashtag-til 3y agoI was looking for some programatic way to create sequence diagrams and came across plantuml, but then I realised it sends your data to their servers so, while I can use for my personal projects, not using for company stuff. Are there any other options to keep sequence diagrams as code and just render it on demand? Edit: http://blockdiag.com/en/seqdiag/examples.html http://blockdiag.com/en/seqdiag/examples.html seems to do what I'm looking for.
- Datagenerator 3y agoYou can create Plantuml diagrams without the server locally using this small Docker ( https://github.com/lrvl/text-to-bmp https://github.com/lrvl/text-to-bmp ) and use "make docker-plantuml"
- fhd2 3y agoYou can just download the plantuml.jar and run it with `java -jar planting.jar`, that's how I usually work with it.
- hashtag-til 3y agoThat sounds like a good idea. Just seen they have a Docker image as well. https://hub.docker.com/r/plantuml/plantuml-server https://hub.docker.com/r/plantuml/plantuml-server
- sanitycheck 3y agoPlus a bunch of plugins for VS Code and major IDEs. One thing I always seem to hit is the default diagram size/memory limits, the FAQ on plantuml.com has command-line switches to override those.
- ink_13 3y agoIndeed there is: https://www.websequencediagrams.com/ https://www.websequencediagrams.com/
- Fethbita 3y ago
- munro 3y agoI clicked the link hoping to see beautiful diagrams to impress my colleagues, but it didn't spark joy. I much prefer the aesthetic of graphviz/google drawings/LaTeX/ggplot2. I think the author is too focused on details that aren't noticed, while the spacing/padding, colors, font, and font size they're using are ridiculous... Practically speaking, if you were to present this it would be illegible.
- 8organicbits 3y agoThe answer may be in the last paragraph, this is the first of a series.
- dpflan 3y agoNo this article has merely highlighted that when you do design things you have to improve it — like group things when it gets too cluttered. The designs and thoughts are simple discoveries one makes when making diagrams. As one can tell these designs are bare minimum blocks connected by lines and grouped visually because it gets crowded. Part 2 is about adding colors and yet more things to this current design that are discoverable by using any existing drawing tool (draw.io, lucid, figma, even MS Paint).
- walterbell 3y agoSample code and generated images for several tools: https://text-to-diagram.com https://text-to-diagram.com
- bloopernova 3y agoThat's really useful, thank you for sharing it. D2 looks to be pretty good compared to the others.
- Veuxdo 3y agoBe advised that the company behind the linked site (Terrastruct) are also behind D2.
- glenjamin 3y agoIn the alignment example from the post there’s a missed opportunity to align the components vertically based on their role The caches should be next to each other, and the servers should be too, leaving the DB up top and the lib between the servers Although personally I’d also then flip it to put the DB at the bottom so the server becomes the headline, and if one server is public and the other internal, then I’d push the internal one down half a row too
- Veuxdo 3y ago"Beautiful" is very hard to maintain when a system starts changing. Think of adding a new box to the middle of an already-busy diagram; it could take an hour to re-align everything. In the 2020s a dev's time is probably better spent using diagrams-as-code[0]. [0] https://www.ilograph.com/blog/posts/its-time-to-drop-drag-and-drop-diagram-tools/ https://www.ilograph.com/blog/posts/its-time-to-drop-drag-an...
- another-dave 3y agoI think how worthwhile that time investment is depends on the reach and longevity of the diagram. Sometimes you're only sketching something out to think things through and you'll get rid of it after 20 minutes. But if at other times, if you've got reference material that's being used to onboard people or explain your system to other teams, etc. that hour spent creating something more understandable probably pays dividends & worth the effort.
- SoftTalker 3y agoAnd in moving things around and re-aliging you have to re-learn the whole diagram. If the frobnitz was always in the upper right part of the diagram and suddenly it's moved to the center left because everything lines up better that way, well maybe it's helpful to someone who is looking at the diagram for the first time but if you've been working with it for six months suddenly it looks like a completely different thing. It's like an ugly UI. It may be ugly but the people who use it, know it. When you "clean it up" you've now disrupted their mental models and they have to re-learn it all over again.
- 8note 3y agoThat's a feature more than a bug. If you want people to look at a diagram and see stuff in it, rather than brush it off by familiarity, you want to move some boxes around.
- bilekas 3y agoThe author does touch on this subject that it's time consuming to amend a diagram. And it absolutely is, if only there was a standardized schema that could be followed properly and then have the tools have an "auto format" option..
- poidos 3y agoI like D2 for this. In a previous role, I wrote a program to parse all of our serverless.yml files (we were doing micro services on AWE) and auto-generate a big D2 diagram from it. It was nice because it would auto-update as the system grew and I wrote it so that the diagram could be broken out into smaller diagrams for each sub system (think splitting on SNS topic)
- lwhi 3y agoI like draw.io ..
- lencastre 3y agoIt’s either PowerPoint or draw.io depending on the time I have and the complexity. Then I found this web based coded solution 1 and I was having more fun then I deserved, especially to quickly add shapes, connections, and not worry too much how it is going to look aesthetically. But then I do worry how it is going to look and I can’t really force where I want the shapes and group them differently, and when I’m adapting myself to the tool instead of the other way around,… I go back to draw.io and screenshot to PowerPoint. 1 — https://nomnoml.com/ https://nomnoml.com/
- lwhi 3y agoThat looks nice; but for flexibility, consistency and getting the job done draw.io is great IMO. Will definitely try out nomnomi tho ..
- beAbU 3y agoI don't understand the first example. The author talks about an unplanned node, literally called it "I was unplanned", and then says "if you have planned ahead"... How can I plan agead for something unplanned, in the context of a diagram? Do I leave sufficient white space around all nodes? Also, the suggested improvement makes it look like "something" and "I was unplanned" are somehow related, or use the same channel/mechanism to interact with "engine"
- bloopernova 3y agoMaybe there will be an LLM that specializes in reading code and generating diagrams. It would be cool if it was able to turn those spaghetti class diagrams into something useful. I'd like to see such a tool make sense of the sprawling terraform we've got, diagrams of which always end up being huge and complex.
- motohagiography 3y agoA visual model should distinguish between: - Levels of abstraction - A transaction - An element inventory - A process - Inputs and outputs Among others. Given the numbers of nodes and edges, the most beautiful or consistent layout would be implied using graph layouts. When we use boxes and lines, we imply meaning to their order and sizes, which might be the case, but most often there isn't, it's just where you had space on the page. The best diagrams are ones you could describe using graphviz/dot because each relationship is a true statement about the system. Sequence diagrams are the next best ones because they force you to close the loop in your thinking, imo.
- tonnydourado 3y agoAs an avid plantuml user, I don't think it's that simple. Graph layouts help, but it doesn't take long for automatic layouts to start to get in the way of conveying meaning, and that's even with a higher level description language, like plantuml or mermaid, let alone with raw graphviz. One can quickly start to spend more time trying to make the layout look right than actually evolving it. Don't have a solution to it, unfortunately. When things in my head start to map too poorly to plantuml, I just consider drawio instead, but it's such a downgrade, that I try to avoid as much as I can.
- knsv 3y agoKnut, Mermaid's creator here. I agree that layout auto-adjustments in flowcharts can be problematic, especially when subgraphs represent architectural subsystems as they are not really flowcharts. :) I'm developing a new Mermaid diagram type for more layout control, with precise block placement.
- blah_why_not 3y ago[dead]
- tonnydourado 3y agoCool! I'm still on the plantuml train, but I like how much easier mermaid is to integrate with (no need for java), so I'm happy to see it evolve!
- hkon 3y agojust give me a tool like enterprise architect with all the drawing capabilities and none of the enterprise features.
- _kb 3y agoThere's strong parallels here with electrical schematics, circuit diagrams and other engineering drawings. There is no singular 'right' way to do it. Just as with code, choosing good abstractions and methods of expression is what separates something from a grok-able idea to regrettable mess. It's not about beauty or aesthetics, it's a tool that requires some active thought and effort to design.
- gtirloni 3y agoFor me, keeping the abstraction level consistent is really hard sometimes. Especially with infrastructure diagrams, it's sometimes hard to stop the urge to add more details at different levels. I wonder if there's a tool that would allow me to easily zoom into a diagram, kinda like those infinite zoomquilt animations.
- Veuxdo 3y ago> I wonder if there's a tool that would allow me to easily zoom into a diagram, kinda like those infinite zoomquilt animations. Ilograph and Structurizr are zoomable. (Full disclosure: I am developing the former)
- ethanbond 3y agoAlso consider checking out icepanel.io Uses the C4 diagramming model and looks really slick exactly for capturing this type of detail
- 123pie123 3y agoI've been thinking and doing this for many years - I've tried very hard to do it with one diagram without luck if you want them to look nice (and I do try to make them as artistic as possible) then I've found that the best/ only proper way to do it, is to do multiple diagrams for different groups of people. complex/ messy one for infrastructure - showing interfaces/ IP address/ security zones/ resiliance/ physical locations/ application binaries/ OS info etc.. sequence diagrams for logic flow of applications basic fancy ones for stake holders/ less technical ppl - crayon type of diagrams for all the diagrams: I find using matching colours (but try if possible, to consider color blind people) and levels of grey (try not to use black) work best... try to group interfaces close together... try not to have crossing lines... symetrical as possible... lines and boxes all aligned with something
- Xophmeister 3y agoMaybe this tool already exists, but it occurs to me that architecture diagrams could be generated from, say, Terraform HCL files. They mightn't be perfect, but if it gets you 80% of the way there -- for final touch-ups with some vector editor or, perhaps, using in-band pragmata via comments -- that seems like a no-brainer.
- bloopernova 3y agoterraform graph Is what currently exists, it generates graphviz that you can then edit to polish. https://developer.hashicorp.com/terraform/cli/commands/graph https://developer.hashicorp.com/terraform/cli/commands/graph
- gtirloni 3y agoThese are awesome tips but hard to get right for people without graphical chops. Is there a tool out there that lets me define them in code somehow? For example, neighbor distance or what symmetry means in a given context?
- vich 3y agoI'm a fan of whimsical.com - it's not code-driven, but does a pretty good job at aligning nodes when making, say a flowchart. Plus, they have a decent library of icons to use.
- jankar 3y agoevergreen content on good visual design of software architect diagrams: http://www.fmc-modeling.org/visualization_guidelines http://www.fmc-modeling.org/visualization_guidelines
- walterbell 3y agothanks for the quality reference & offline PDF, http://www.fmc-modeling.org/download/visualization_guidelines/FMC-VisualizationGuidelines.pdf http://www.fmc-modeling.org/download/visualization_guideline...
- jxf 3y agoI attribute a large part of my technical leadership success to being able to communicate clearly through diagrams, and I think the post gives some good entry-level practical advice. One more piece of advice I'd have is to either make sure your picture tells a story, or to be able to tell a story using your picture. Humans are social creatures who have learned to share information through stories, and you'll make a much bigger impression on others if you can weave your picture into your story.
- 8note 3y agoSame here, and I thought it was missing the first step of the drawing, which is defining what it is that you're trying to get across. The story is especially handy when you're drawing it in real time on a whiteboard
- tdba 3y agoThe general competency level of diagramming in most engineering teams is low enough that I think it's better to talk about what to diagram rather than how to visually lay it out. Everyone has heard of sequence diagrams (and for good reason!) but do you use data flow diagrams? https://en.m.wikipedia.org/wiki/Data-flow_diagram https://en.m.wikipedia.org/wiki/Data-flow_diagram
- tamiral 3y agomost places i've worked at had no semblence of data flow diagrams!
- forinti 3y agoI studied Structured Analysis at university and still have a couple of books on the subject, but I never used it professionally. I had a lot more experience with UML, but that too has gone out of fashion. Nobody models anything anymore, not even ER diagrams are used. Knowledge ends up scattered between a million tasks in some project management software. Often, things are not even written down, because "there's not enough time".
- xtracto 3y agoOne of the things I recommend to the startups I advise is to include documentation within the repository. I always try to have a /doc directory which includes Markdown (I like using [1] self rendering markdown pages) and MermaidJS (For which I also created a dumb self rendering script [2]). That way Merge Requests can be blocked for lack of documentation, or lack of documentation update. MermaidJS have been a godsend for documentation. [1] https://github.com/jcbhmr/ezmdpage https://github.com/jcbhmr/ezmdpage [2] https://github.com/obaqueiro/mermaid-js-auto-renderer https://github.com/obaqueiro/mermaid-js-auto-renderer
- Hel5inki 3y agoThis is interesting, do you have an example repository with that setup? My team currently uses Swagger for documentation which provides decent documentation for us, so what sort of documentation at the repository level could I gain by using this setup instead or in combination? Also, how would one detect that the documentation has been correctly updated aside from manual inference?
- darkwater 3y agoAnd that's why, kids, it takes me always a week to draw a simple diagram. That arrow is unaligned, I have to fix it. I forgot to add that component, now I have to shuffle things around. Let's group all these blocks together so I can move them. Wait, I need to add another block inside, I have to ungroup them and shuffle. etc etc etc