[HN Gopher] Ask HN: What diagrams do you use in software develop...
___________________________________________________________________
Ask HN: What diagrams do you use in software development?
There's currently an article on the front page about the death of
UML[2]. While UML's inheritance diagrams have been dead to me for a
long time, I still like the sequence diagrams. Besides that I
sometimes still draw ERDs and I love JJG's Visual Vocabulary[1] for
drawing "interaction diagrams". What types of diagrams do you use
with your team? [1]: http://jjg.net/ia/visvocab [2]:
https://news.ycombinator.com/item?id=26934577
Author : cies
Score : 216 points
Date : 2021-04-26 08:52 UTC (14 hours ago)
| thelastinuit wrote:
| https://www.nomnoml.com/
|
| http://chartmage.com/index.html
|
| https://swimlanes.io/
|
| https://dbdiagram.io/home
| 8note wrote:
| I mostly draw data flows. Draw a bunch of boxes representing
| different services and sometimes different components, and
| labeled arrows describing where events/data flows.
|
| When that's not sufficient, usually a sequence diagram adds a
| whole ton of clarity
|
| For reviews with new people, a limited ERD is handy, mostly to
| show where the 1:n or n:n relationships are
|
| I somewhat frequently write truth tables to get a good breakdown
| of different usecases
|
| I use web sequence diagrams for my sequence diagrams, but mostly
| everything else I'm drawing by hand in paint 3d with the
| surface's nice pen drawing
| laci27 wrote:
| https://draw.io But dbdiagram.io looks amazingly easy to use. And
| so are the rest of the suggestions. I also realize that I don't
| use UML with draw.io:)
| regus wrote:
| I used to make my diagrams in draw.io but I find that I spent way
| too much time fiddling with the way the diagram looked rather
| than the thing it was modeling. Also it is a huge pain to have to
| go back and make revisions to the diagram. After presenting
| diagrams to stakeholders they would always ask for changes and I
| would end up having to redraw everything.
|
| I recently stumbled upon code to diagrams tools like app2code and
| plantuml. I really enjoy this because I can focus on the model
| and not the aesthetics. Also making revisions to code is a lot
| easier than fiddling around with draw.io.
|
| Does any one have any tools like this they can recommend?
| splittingTimes wrote:
| Mental model often formed much more around what kind of data
| flows and interactions happen between components.
|
| As a big fan of Domain Driven Design I found "domain
| storytelling" a useful technique when adapted to software
| systems.
|
| With these diagrams it was much easier to convey complex systems
| and their temporal couplings. Especially to higher Management as
| they can actually "read" how the sequence of events flow.
|
| Try it out and see if it can be another tool on your belt.
|
| ===
|
| https://domainstorytelling.org
| mih wrote:
| Seconded. Software support for drawing and visualizing the
| approach is quite lacking at the moment though. The editor they
| provide at least offers a starting point [1][2].
|
| [1] https://www.wps.de/modeler/
|
| [2] https://github.com/WPS/domain-story-modeler
| crispyambulance wrote:
| POWER POINT.
|
| Because I just want some shapes, lines and clip-art to
| communicate an idea clearly, quickly, and informally.
|
| I remember the UML days and their endless variety of turgid
| tools, don't want to re-live those experiences.
| astatine wrote:
| Sequence diagram with PlantUML and deployment diagrams with
| Gliffy. Every other type of diagram has fallen by the wayside,
| over the years. PlantUML with Visual Code is a breeze and makes
| life easy.
| bmn__ wrote:
| We visualise certain data structures (DAGs and trees) for
| debugging and documentation with https://graphviz.org (EPL) and
| https://yworks.com/yed (proprietary, freeware).
| benfrancom wrote:
| Architecture and Data flow diagrams. Usually I sketch it out on
| paper and transcribe it to Lucidchart. Recently, I had to
| troubleshoot connectivity issues in Amazon RDS in a private
| subnet with AWS Data Migration Service. This was a regulated
| environment with heightened isolation. I was only able to figure
| out the problem once it was on paper and could see it visually
| with the various Security Groups described.
| emmanueloga_ wrote:
| This [1] is not something I use but something that's been on my
| radar for a while and I would like to investigate:
|
| "IFML provides ... tools for the definition of Interaction Flow
| Models that describe the principal dimensions of an application
| front-end."
|
| Just a few days ago there was a thread about the death of UML...
| like anything from omg.org, I suspect there's a useful subset to
| carve out that could be useful to model applications.
|
| 1: https://www.omg.org/spec/IFML/1.0/PDF
| bsldld wrote:
| Markdeep[0] from Casual Effects has a way of drawing diagrams
| using extended markdown.
|
| I used it to write this document with two diagrams: https://loan-
| free-ed.neocities.org
|
| Other tool I like are PlanetUML[1], BoUML[2] and Modellio[3](it
| is very heavy though on system resources!)
|
| [0] https://casual-effects.com/markdeep
|
| [1] https://plantuml.com
|
| [2] https://bouml.fr
|
| [3] https://www.modelio.org
| anyonecancode wrote:
| I'm a big fan of sequence diagrams, especially those that can be
| generated from markdown-like syntax. I use Lucidchart at work,
| but there are a few free options as well -- in this comment I'm
| trying to advocate for the concept rather than a specific tool.
|
| Sequence diagrams, to me, give the benefits of a flow chart, but
| with a much tighter explanation of the actual flow and
| relationships. You can read them from the upper left corner to
| the lower right, just like (western) writing. You get not just
| the entities involved, and not just the way they are connected,
| but the _ordering_ of those connections, which I find super
| helpful. The concept is simple enough that I can hand draw it on
| a whiteboard or scrap of paper, and for electronic formats, if
| you generate these from markdown you now have the same data in
| both a visual and textual format (handy for folks who have a
| harder time accessing pure visual presentations), and auto-
| generation from text makes it easy to update and so more likely
| to maintain as the system changes.
| billfruit wrote:
| Statecharts often provide a mote complete picture of behaviour
| than sequence diagrams.
| pjmlp wrote:
| UML and Entity Relationship ones.
| viraptor wrote:
| Any diagrams. After learning about the uml and other ideas and
| trying things in practice over the years, I found that any
| diagrams is better than no diagram. But also a diagram that shows
| what you want to show is better than a diagram which complies
| with a specific idea/standard but may not represent what you
| need. Need to mix sequences and inheritance on one diagram for
| some reason? Just do it (making sure that there correct
| annotation / legend available)
| blumomo wrote:
| I use the FMC - Fundamental Modeling Concepts language to draw
| systems and architecture diagrams. The beauty of FMC is that only
| two node types exist, both having very clear semantics (depending
| on which of the 3 diagram types you draw/read). In a systems
| diagram a sharp rectangle represents an actor and a rounded
| rectangle/circle represents a persistent/volatile memory. You can
| only ever connect an actor with a memory (space), I think it's
| called a bipartite graph.
|
| My university took part in its research (less nowadays) and I'm
| really glad I had the chance to learn it. I still use it at work.
|
| [0] http://www.fmc-modeling.org/
| randrus wrote:
| Also a big fan of FMC for architecture diagrams - in bigger
| systems, being able to easily distinguish "action" vs "state"
| nodes has been useful in reasoning about behaviors. Pity it
| never took off, and there doesn't seem to be much tooling for
| it.
|
| For other uses - yeah, ERD and sequence diagrams are the
| workhorses.
| mr_tristan wrote:
| I found there are two types of diagrams I lean on, almost always
| for higher-level explanation-style documents:
|
| 1. System architecture 2. Flowcharts
|
| NOTE: I don't try to mix the two. Architecture diagrams are the
| what, not the how. I find a lot of people try to mix them.
|
| Beyond this, sequence diagrams are useful.
|
| I use these for explanatory documentation, mostly. Like, we have
| a "architecture guide" for each service we maintain, that usually
| contains a system architecture diagram, and maybe a flowchart of
| the "happy path" processing. But these are simplified versions
| things... like, I usually leave configuration details, like
| networking and access control out of the architecture guide, and
| just focus on "what services are interacting with each other
| directly".
|
| Also, LucidChart has an "AWS import" method, that actually works
| well, but can be a little like drinking from the firehose. It's a
| solid tool, but mostly as it's own kind of reference document,
| like, API documentation for your AWS stuff.
| zozbot234 wrote:
| I'm a bit surprised about the use of flowcharts, specifically.
| Do they really add much over just writing down the same content
| in pseudocode notation?
|
| From a theory-focused POV, flowcharts are supposed to be
| essentially complementary to dataflow diagrams. But the latter
| are often more useful for practical concerns.
| marvinblum wrote:
| I use ER diagrams to model data structures, even if they are not
| stored in a database. I find them to be much clearer than class
| diagrams for example, and they help to keep an overview of
| everything. Otherwise, I sometimes use activity diagrams to model
| some complicated logic but don't use anything else of UML.
| hantusk wrote:
| I use mermaid: https://mermaid-js.github.io/mermaid/#/
|
| And excalidraw: https://excalidraw.com/
| rwoerz wrote:
| UML component, deployment, state chart, class, use case and
| activity diagrams. I mostly use PlantUML, which is, due to its
| textual source notation, embeddable into Markdown or AsciiDoc
| files and are therefore comparably easy to version.
|
| PlantUML works best with sequence diagrams because automatic
| layout is much easier ("sequential") for them.
| bayindirh wrote:
| I generally design my software in StarUML and generally use class
| and sequence diagrams.
|
| I'm not using it as a UML tool strictly, but being able to
| document everything, generate the document in HTML and being able
| to store it alongside design documents help me a lot.
|
| Small algorithms are hand drawn first, and documented extensively
| in code. If they're crucial for the research I'm doing, I carry
| them to the same StarUML document too.
| tootie wrote:
| Nothing most of the time. Maintaining diagrams is pain and rarely
| reflects reality. We have all our services in AWS and it doesn't
| take long to trace backwards from DNS if I actually don't know
| how something works.
| jjuhl wrote:
| I don't use any tools at all. Keep diagrams in my head - if they
| are too complex for that then there's a different problem to be
| solved.
| pezo1919 wrote:
| I realized that the only UML diagrams really helped me back in
| school were behavioural diagrams: sequence diagram and activity
| diagram. They describe the hard parts of programming/complexity.
|
| Structural diagrams: do not "solve" anything really. (I know,
| they might be good for docs...)
|
| Also recently I started to think in terms of events. Look up FRP,
| "real OOP" and Cycle.js.
|
| For these, there is no standard diagram yet, so I am came up with
| my own - still under change.
|
| For that, I started to use Lucidchart, because its available on
| mobile/tablet as well in browser as desktop view and it gives
| full functionality.
|
| It's also really nice & snappy.
| coward76 wrote:
| Sequence diagrams, state transition diagrams, and network
| diagrams provide the most value to the development teams I have
| been working with.
| pydry wrote:
| Hand drawn. I like the idea of building diagrams I just tend to
| find that:
|
| * It's a lot of work to make them look right.
|
| * They become outdated SO quickly. They're dangerously misleading
| as often as they're useful.
|
| * Lots of people like to create diagrams, nobody likes to
| maintain.
|
| Hand drawn dated diagrams have a sort of built in advantage that
| people will assume that it's not been kept up to date, especially
| if it's scruffy. Also they're quick.
|
| I like the idea of generated diagrams better than drawn diagrams
| but unfortunately the software just isn't there yet.
|
| Even when you can do it, they usually look shit because the
| program won't layout nearly (e.g. E/R) and you can't integrate
| changes to the source (e.g. tables) to annotations/tweaks.
| jiehong wrote:
| But hand drawn diagrams are invisible to people with visual
| deficiencies.
|
| Usually, plantuml source is more readable, and it's just almost
| like writing a list so it's not too much work.
| grammarnazzzi wrote:
| > it's just almost like writing a list so it's not too much
| work.
|
| But written lists are worthless to people who are illiterate
| pydry wrote:
| I don't find plantuml at all readable as a DSL.
|
| I like the idea of some sort of textual dsl that generates
| diagrams just not _that_ one and ideally not a UML focused
| one.
| Veuxdo wrote:
| Have you looked at Ilograph? Its DSL is much nicer than
| PlantUML and isn't UML-focused.
| globular-toast wrote:
| The topic is about diagrams, though. The point is using
| visual aids to help with development so that implies being
| able to see stuff. If I had a visually impaired developer on
| my team then of course I would make other provisions, but I
| would still draw diagrams for myself and other members.
| bostonsre wrote:
| Yea, I like the idea of having freely draw diagrams where you
| aren't constrained to a certain syntax. I used to only do hand
| drawn diagrams until we started using miro at my company. It's
| really intuitive and the simplicity and the control just make
| it so much faster and easier to generate and maintain diagrams.
| It's been great for design and has been useful for debugging
| issues in unfamiliar architecture.
| globular-toast wrote:
| Agreed! Hand drawn is quicker, way more flexible, and everyone
| knows how to do it.
|
| It has a built in version control system: get a new piece of
| paper and keep the old one.
|
| There is immense power in "reciting" the diagram in front of
| someone on a new piece of paper or whiteboard. It's essentially
| adding a whole new dimension to your diagram, as well as space
| for discussion and interaction along the way. I've not seen
| someone pull this off well in any electronic format.
|
| Spending time refining diagrams is what you do when you're
| writing a thesis or book. You have to be very careful when
| designing your diagrams this way. But it's a complete waste of
| time when the diagram is for software under development. Those
| diagrams can and will become outdated very quickly.
| montroser wrote:
| Hand drawn diagrams often have a clarity still elusive in
| diagramming software.
|
| But we have found that working together in real time -- making
| a diagram together -- is an incredibly efficient way to
| strategize about how to solve whatever problem at hand, and
| then come away with a shared understanding so we can work
| together on the execution.
|
| We use Plectica[1]. Another popular one is Miro[2].
|
| [1]: https://beta.plectica.com
|
| [2]: https://miro.com
| splittingTimes wrote:
| Simple Diagrams is great for this. Can vouche for it.
|
| ===
|
| https://www.simplediagrams.com/
| Pinus wrote:
| Lately I have been wondering whether a "fear" (for want of a
| better word) of hand-drawn diagrams are causing diagrams in
| general to be under-used. We're used to having everything
| typed, TeX:ed, machine drawn, perfect, and we want our diagrams
| to look like that, too, but using drawing software is hard and
| time consuming, so we don't diagram at all. But we could just
| whip out pencil and paper! You don't have to be an artist to
| draw some boxes and arrows. And the problem of archiving and
| revision control is solved now that everyone has a digital
| camera in their pocket (and a JPEG file of an A4/letter page
| isn't very big by today's standards).
| beaconstudios wrote:
| The best planning experiences I've had in a team were when
| everything was done on a whiteboard and photographed for
| posterity. Architecture planning, kanban board, UI mockups,
| everything - it was a joy not having to wrestle opinionated
| tools into doing what we wanted.
| benhurmarcel wrote:
| Since I have a tablet and stylus I started sending/showing a
| lot more diagrams. It's easier to share and looks cleaner
| than a photo of a paper.
| withinboredom wrote:
| I use Microsoft research's Lens. It's amazing for taking
| pics of whiteboards and drawings and making it look much
| better than a photo of paper.
| billfruit wrote:
| Some of the diagrams are not viable to draw by hand.
| Statecharts for eg, derives much of their expressivity from the
| ability to nest them without limit. Such nested Statecharts
| require a system which can collapse/expand nested levels, and
| hand drawn diagrams cannot do that.
| jerome-jh wrote:
| I like sequence diagrams and state diagrams (well just straight
| finite state automata). They bring an extra layer of description
| that is otherwise very hard to extract from the code.
|
| I draw them with Plantuml. Text input is really a must have for
| me. On crowded diagrams it may be difficult to fine-tune the
| layout though.
|
| I still sometimes do class diagrams, although I do not find they
| carry much info compared to the code. The meaning of arrows is
| ambiguous and they're too verbose. APIs are better documented
| with e.g. Doxygen.
| 49yearsold wrote:
| I frequently communicate architecture with diagram that simply
| contains following three things: - boxes (rectangles with text in
| them) - arrows connecting these boxes - and some brief text to
| convey any architecture/ideas
|
| Apart from this, sometime I also use "sequence diagrams" -
| vertical lines representing systems/modules to illustrate the
| sequence of flow of any system/user action.
| alfiedotwtf wrote:
| Control Flow diagrams to work out logic, turn that into
| pseudocode in comments, then start implementing under each
| comment.
|
| Also, ER diagrams because it's easy to translate drawing to
| normal form
| andyjohnson0 wrote:
| The only uml diagram I've really used in the last decade or so is
| the sequence diagram - for describing use cases for network
| message exchanges. And even that is in powerpoints and on
| whiteboards. I can't imagine ever formally documenting anything
| that way. Too bulky.
|
| I try to avoid over-use of inheritance, so class diagrams don't
| get used for that. Mostly I use unstructured boxes and arrows for
| entity-relations, and don't worry too much about notational
| rigour.
| cies wrote:
| And beyond the UML diagram family? ERDs maybe?
| ta988 wrote:
| I'm usong diagrams.net all the time. It is even my go to
| explanation tool in meetings (virtual or not). Just open a
| window, start drawing concepts and linking them. I found out that
| it makes it much easier for the audience to grasp what is
| happening rather than already made slides.
| kcartlidge wrote:
| We use a lot of sequence diagrams.
|
| So much so that thanks to https://bramp.github.io/js-sequence-
| diagrams/ I've got a Netlify-powered static site for creating
| them interactively at https://sequence-diagrams.netlify.app/
| using their JavaScript library.
| drittich wrote:
| We use PlantUML with markdown in our internal wiki. The pros are
| a) that you can understand the markdown on its own, b) we can
| diff changes to the diagrams, and c) the source code is very
| small. The main downside is people are more used to drawing than
| coding diagrams (even developers), and the output quality of
| PlantUML leaves a LOT to be desired, by today's standards.
| tluyben2 wrote:
| I like bpmn workflows. Especially with the Camunda editor. Not
| for execution, but for quickly drawing up logic and flows to
| explain how I suggest we do things. Those diagrams are complete
| enough to encompass everything: low-level logic to high level
| cloud and system architecture.
|
| And everyone understands them without any help or explanation.
| Molomby wrote:
| If you have complex interactions sequence diagrams can be a
| hugely helpful communication tool. I use
| https://sequencediagram.org/ quite often. It's a free, in-browser
| tool that lets you create/edit/export diagrams using markup.
| Takes some getting used to but I much prefer it to dragging
| arrows around manually.
| amelius wrote:
| Most designs can't be planarized that easily, so I don't use
| diagrams.
| mbar84 wrote:
| https://mbarkhau.keybase.pub/asciigrid/
| Graffur wrote:
| draw.io - it's the best and it stores locally
| itsArtur wrote:
| I like the C4 model because it forces me to think about the right
| level of abstraction for the diagram's audience. It also has very
| few core building blocks and thus is very easy to learn. I just
| wish the tooling around it was better :)
| NicoJuicy wrote:
| PlantUML had support for c4
| Hypergraphe wrote:
| Hi, there are several draw.io plugins available on github do
| use C4 in draw.io if you are not already aware of this.
| _ZeD_ wrote:
| don't think of a "luddite" comment, but, apart some online tool,
| like websequencediagrams or drawio, I find a necessity to just
| doodle some informal diagrams with pen and paper, mostly to
| understand the "hi-level" architecture of a solution (where "hi-
| level" spans from source modules dependencies to microservices /
| db dependencies to "macro" stuff)
| pintxo wrote:
| Most often used are process diagrams: My preferred tool here is
| the great text editor based: https://sequencediagram.org/
| Rochus wrote:
| I used a lot of Objectory and UML diagrams in the nineties,
| mostly for specification and presentation reasons; don't remember
| when I used one last time; must be more than ten years ago; from
| my point of view UML is overkill most of the times; usually takes
| more time to explain to people what all the sophisticated symbols
| mean than e.g. simple block diagrams; and systems tend to be so
| big these days that UML diagrams become too big and confusing; we
| had the same evolution in hardware development; schematic
| diagrams were almost completely displaced by hardware description
| languages (such as Verilog) because systems became much too big
| to be decently modeled with diagrams. EDIT: it's worth taking a
| look at this article: https://modeling-languages.com/uml-
| opinions-creators/
| simonsarris wrote:
| I actually make a diagramming library for the web, called GoJS,
| so that other programmers can quickly add interactive diagramming
| capabilities to their web apps: https://gojs.net
|
| So I make all kinds of diagrams, mostly as demonstrations. When
| developing a library itself, especially one where there are
| phases (Graph Objects must measure themselves and their parts,
| and draw in a certain order, and not more than they need to),
| state machine-style and flowchart-style diagrams are awfully
| helpful.
| billfruit wrote:
| Most important UML diagram as per my experience are StateCharts,
| even more than Sequence Diagrams, it can indicate behaviour,
| including time outs, and possibly exceptional circumstances.
| flarg wrote:
| Archimate for high level architecture, uml for more detail, and
| masala diagrams (that's what we're calling them right?) in ppt
| for marketecture
| keraf wrote:
| Flow chart, sequence and class diagrams are the ones I use the
| most in my current job.
|
| In source, I generally use Mermaid[1] as its syntax is easily
| maintainable and understandable. And our documentation (mdBook)
| is written in markdown and can render Mermaid via a plugin[2].
|
| When drawing quick diagrams during online communications, I use
| Excalidraw[3] as it's easy to use and has a nice whiteboard style
| to it. When I'm with my team (pre-covid), whiteboard or paper did
| the trick.
|
| [1]: https://mermaid-js.github.io/ [2]:
| https://github.com/badboy/mdbook-mermaid [3]:
| https://excalidraw.com/
| agentultra wrote:
| I mainly use diagrams in documentation and not in specification
| or development (although tools I am learning to use, such as
| Alloy [0], for specifications do generate diagrams of the state).
|
| In documentation I typically use a mix of ditaa[1], mermaid[2],
| and graphviz[3]. I used ditaa for architecture diagrams, a mix of
| sequence, flow chart, and ER diagrams in mermaid to explain
| protocols or interactions; and I use graphviz usually for
| datastructures or dependencies, etc.
|
| [0] https://alloytools.org
|
| [1] https://ditaa.sourceforge.net
|
| [2] https://mermaid-js.github.io/mermaid/#/
|
| [3] https://graphviz.org/
| Gehinnn wrote:
| I use drawio, as those diagrams are quite future proof (drawio is
| open source, very old and you can embed diagrams in svg files)
| but also very expressive (you can even use latex inside drawio
| diagrams).
|
| Since I created a drawio integration extension for VS Code, I
| tend to create much more diagrams during coding, as they are
| really cheap to create. There is also an extension for IntelliJ
| and the diagrams work nicely in github readme files. After moving
| diagrams closer to code, I noticed that it is much easier to keep
| them in sync with the code base. Especially as PRs changing the
| code structure can include diagram changes at the same time.
|
| I use them to model simplified class diagrams for documentation
| purposes, to model data flows, to create primitive mockups, to
| show the relationship between UI components (as embedded
| screenshots) and to show component dependencies. I try to follow
| UML, but I don't care about machine readability and prefer
| readability over UML compliance.
|
| You can find some uses-cases of those diagrams here
| (https://dev.to/hediet/create-diagrams-in-vs-code-with-
| draw-i...).
| tda wrote:
| Thanks for the extension! Don't make that meany diagrams but
| when I do I use it. Much easier than going to the draw.io in
| the browser as the extension can easily access the files in the
| source code
| simlevesque wrote:
| Could you add a link to your extension please ?
| Gehinnn wrote:
| You can find it here: https://marketplace.visualstudio.com/it
| ems?itemName=hediet.v...
|
| Like draw.io, it is open source!
| (https://github.com/hediet/vscode-drawio)
| gonzo41 wrote:
| Yeah my top 3 is websequencediagrams, PowerPoint and draw.io
| All depends on the information I'm trying to convey and the
| formality, Truthfully, PowerPoint is my goto for explaining
| flow and quick 'this speaks to that' style network stuff.
|
| I also get a bit of millage from time to time out of the
| Graphviz online demos. I use those to throw together graph-ish
| stuff on the fly.
| jimbob45 wrote:
| Came here to say this. It's free and it does a great job.
| kwanbix wrote:
| draw.io is great, however, isn't the question about what type
| of diagrams do we do instead of what software do we use to do
| diagrams? I am confused.
| notRobot wrote:
| Draw.io is amazing!
|
| It has now been renamed to diagrams.net:
| https://app.diagrams.net/
|
| Github repo: https://github.com/jgraph/drawio
|
| It's very easy to self-host, especially on Github Pages:
| https://github.com/jgraph/drawio#running
|
| There's also desktop apps for Windows, GNU/Linux, Mac and
| Chrome OS: https://github.com/jgraph/drawio-
| desktop/releases/latest
| capableweb wrote:
| At first, the naming change seems useless. At second thought,
| it might help with discovery as "draw" is very generic (end
| up calling it "draw io"). Third thought is why did they chose
| something generic again, instead of creating a unique name?
|
| The name draw.io seems to be everywhere in the
| code/documentation/community/stack overflow still and even
| searching for "draw io" shows "Draw.io - Diagrams.net" which
| just adds to the confusion.
|
| Probably either names would have been fine, but at least be
| consistent about it.
| Gehinnn wrote:
| Afaik they only wanted to get rid of the io tld, as it is
| quite insecure.
| pcthrowaway wrote:
| What makes the .io TLD insecure?
| avereveard wrote:
| I'm mostly producing component diagrams where we detail
| communication interfaces and services responsibilities; those are
| stable, long running and broad enough that one they don't become
| immediately obsolescent and still are granular enough that they
| can convey useful information to whomever reads them
|
| we also do produce some reverse engineered code map with doxygen
| here and there, so we can cut down cross dependencies and
| dependency cycles as the codebase matures
| hcarvalhoalves wrote:
| - Entity-Relationship Diagrams
|
| - Sequence Diagrams
|
| - State Diagrams
|
| - Activity Diagrams
|
| I use PlantUML to render all these, with the added benefit of
| being able to produce it programatically.
| yrgulation wrote:
| I use draw.io for high level architectural diagrams, both for oop
| code and infrastructure. When on site i use whiteboards and
| pictures of them, then if time allows i move them over to
| draw.io. I almost never draw implementation diagrams. These can
| be extracted with tools like doxygen.
| jifii3 wrote:
| Semi smart-ass answer: Whatever is the simplest one to
| communicate what I'm trying to say.
|
| I don't strive to be 100% compliant with a given methodology, I
| see those as diminishing returns. Class, sequence, architecture,
| a bunch of lines and boxes, whatever does the job.
|
| It depends on your audience & message!
| roland35 wrote:
| I don't use strict UML, but I still find it useful to do work
| with block diagrams of systems to show relationships of major
| components.
|
| I used to use Yed, but now I like drawio.
| vladojsem wrote:
| We are makers of gleek.io diagram maker https://www.gleek.io/ and
| we use this tool internally as well.
|
| When I create diagrams I prefer typing than drag-and-dropping and
| gleek.io is pretty fast.
|
| You can check the diagram examples:
|
| * Basic shapes https://app.gleek.io/diagrams/basic
|
| * ERD crows foot https://app.gleek.io/diagrams/erdiagram
|
| * UML class diagrams https://app.gleek.io/diagrams/class
|
| * UML sequence diagrams https://app.gleek.io/diagrams/sequence
|
| Recently we made also video tutorials, hopefully it helps when
| you are learning to work with a tool:
|
| https://www.youtube.com/channel/UCMl_1_jjnhgPAsRBuJ0yzAA
|
| Feel free to ask anything, happy to help!
| kazinator wrote:
| > _While UML 's inheritance diagrams have been dead to me for a
| long time, I still like the sequence diagrams._
|
| Common sentiment, I suspect.
| oneplane wrote:
| ASCIIFlow and Draw.io as both are not bound to some specific
| program and you can commit both to git.
|
| UML is pretty much dead, so 'standard' diagrams are not worth the
| effort unless contractually requested.
| mzaccari wrote:
| I've recently started using Terrastruct, which I've come to enjoy
| as I feel like I can quickly put together business logic and
| share it with the team without the tool getting in the way:
| https://terrastruct.com/
| fsloth wrote:
| I find that if problem is formalized enough that it could be
| mapped to specific diagram schema it's actually easier just to
| start coding it.
|
| But before the formal idea is developed I just sketch in whatever
| diagram grammar seems most appropriate for the problem.
|
| We don't really use diagrams for formal communication. Most
| formal discussions are around concrete schemas and API:s.
| heyoo wrote:
| Rich drawings in draw.io.
|
| Sequence diagrams in PlantUML (using the awesome VScode
| extension)
| TeddyDD wrote:
| Sometimes I use DRAKON. It's useful for untangling complex
| algorithms.
|
| [1]: https://drakonhub.com/en/drakon
| thelastinuit wrote:
| effing loving that tool.
| lugu wrote:
| +1 It forces me to express in the most simple way the
| intention behind the code.
| bullen wrote:
| I made this tool 15 years ago:
| http://move.rupy.se/file/logic.html
|
| It has been used for everything from SQL design to quest
| scripting in games.
|
| I don't use it anymore because I made my own JSON database:
| http://root.rupy.se
| adflux wrote:
| Visio. I like the large amount of styling options, installable
| Azure component packs.
| hatchoo wrote:
| I use excalidraw for high level diagrams. Love the handdrawn feel
| to it. There's a feature to collaborate too but I haven't tried
| it yet.
| nablaone wrote:
| * Simplyfied subset of UML (sequence, state ...) - on whiteboard
| (pre covid), now google docs. These diagrams do not last long.
| We're using them for discussion and some documentation. * ERD
| using our tool (we eat our own dog food). This one is crucial.
| Code and migration scripts are generated from it.
| joelschw wrote:
| dbdiagram.io for ERDs these days:
|
| https://dbdiagram.io/home
| stared wrote:
| TikZ:
|
| - http://www.tcs.uni-luebeck.de/downloads/mitarbeiter/tantau/2...
|
| - https://texample.net/tikz/examples/tag/diagrams/
|
| - https://www.overleaf.com/project/5c73f8d11e30574803429a04
| sidcool wrote:
| C4 model helps for existing architectures. I use Mural for that.
| cies wrote:
| Did not know of this, thanks for mentioning. I think this can
| help me to make my architecture diagram less loosely defined.
| cies wrote:
| To answer my own question (I forgot to mention some):
|
| * ERDs
|
| * UMLs sequence diagram
|
| * State diagrams
|
| * JJG's VisVocab (for diagramming interaction, i.e.: screens and
| actions): http://jjg.net/ia/visvocab
|
| * And some (not well defined) type of architecture diagrams
|
| * Sometimes a branching diagram to explain a hairy git branching
| issue to a co-worker
| tomerv wrote:
| The C4 Model looks pretty good, it's like a very simplified UML.
| The main selling point for me is that it's very intuitive to
| understand without knowing anything about it in advance. However,
| I don't have much actual experience with it so far, so I'm still
| not certain it's the best solution.
|
| https://c4model.com/
| smoe wrote:
| I found the first 2 levels of c4 very useful to get a quick
| sense what the system consists of, what it interacts with and
| who the users are. Also because it is something non-tech people
| can understand and reason about.
|
| But for level 3, 4 it gets tedious to do the diagrams at time
| and harder to keep them updated over time. Personally I prefer
| to just read the code and only have diagrams in special cases
| at this point
| jasonpeacock wrote:
| C4 Model + PlantUML is the the best combination.
|
| You can version your diagrams with your code (or in their own
| repo) using PlantUML, and by following the C4 Model you create
| digestible diagrams that are easy to understand.
| linkdd wrote:
| This.
|
| The main selling point for me was the "zoom in/out" aspect.
| Instead of having a HUGE UML diagram, you have a bunch of small
| diagrams, each focused on a single part of the described system
| and the interactions between its components.
| Hypergraphe wrote:
| +1, I use this too.
| marton78 wrote:
| I second the C4 model, its concept of different zoom levels is
| great! It guides thinking when specifying an architecture, and
| is a great didactic device when explaining said architecture to
| executives / investors.
| vaughan wrote:
| I was thinking today we need a communal collection of diagram
| templates that we can reach for instead of re-making our own each
| time.
|
| I shouldn't have to re-adjust my mental model because of some
| stylistic/level-of-detail decisions by the author.
|
| These diagrams would be interactive too.
|
| Many systems are very similar in what they do. There are many
| times I am asking myself: "but how is this different from <well
| known architecture pattern>".
|
| Think about categories like append-only logs, search indexing,
| web requests, git trees, etc.
|
| I'd love to be able to diff against two diagrams to the same
| problem and see how the approaches differ.
| irrational wrote:
| Years ago we found it useful to generate a database diagram. Each
| table had its own box with the columns in the table, their data
| types, default values, etc. Lines would connect the boxes
| indicating foreign key relationships. Back then we were using
| oracle. The program would connect to the database and run DDL
| queries to build the boxes and lines. Then we could group the
| boxes (all the user tables over here and colored blue) manually.
| Periodically we'd generate a large pdf and send it to the print
| shop to be printed and hang it up in our work area.
|
| I can't remember what program we used. But now we are on Postgres
| and we talk about creating a database diagram again since we
| found it so useful. We just haven't found a good program yet.
| rrrrrrrrrrrryan wrote:
| ERD software that connects to databases is plentiful. I'm not
| sure what tools are commonly used in the Postgres world, but
| "ERD" is the term you'll want to use in your googling.
| EB66 wrote:
| I'm surprised there's only one other person in this discussion
| who has mentioned swim lanes. They are incredibly useful!
|
| Swimlanes are basically process flow diagrams (aka flow charts)
| but with lanes that indicate which actor or system performs each
| process.
|
| At my company, if an engineer gets tasked with a logically
| complex feature or a feature that involves multiple different
| systems, then we will often require them to use swimlanes to
| diagram out their new feature before they start coding it. The
| flow chart makes it easier for the business owner to double check
| the logic before it's implemented. The lanes help the engineer
| better understand more intuitive ways to organize their code
| (classes, methods, etc) and the interactions it will create.
| Without the lanes, code organization on logically complex
| features involving multiple actors can go off the rails pretty
| quickly.
|
| For database table specs we use ERDs.
| motohagiography wrote:
| I use Sankey diagrams with D3.js for a lot of security
| architecture work.
| captaincaveman wrote:
| When useful:
|
| Component diagrams, what is connected to what?
|
| Activity diagrams, what are the activities that happen, and have
| they got names?
|
| Sequence diagrams, so microservices on top of microservices, hmm
| please show me how you get item x?
|
| State Diagram, are you sure you have got all the possible state
| transitions?
|
| ERD diagram, Chen style, I don't like it when the look like SQL
| tables (maybe we don't have/want/need a relational database, so
| lets not start shaping it like one at the concept stage). The
| physical/logical models I don't see much value diagramming.
|
| BPMN can be useful alternative to Activity diagrams sometimes.
|
| edit: left off Use Case diagram, so simple yet seen teams
| struggle so many times to articulate this.
|
| A key thing about doing a diagram or document is that they force
| you to clarify your understanding. Another rule of thumb is if
| you are struggling to keep you docs/diagram in sync with your
| implementation, you have likely made you docs too detailed, its a
| high level map to guide not a detailed set of instructions on how
| to construct.
| zerkten wrote:
| > A key thing about doing a diagram or document is that they
| force you to clarify your understanding. Another rule of thumb
| is if you are struggling to keep you docs/diagram in sync with
| your implementation, you have likely made you docs too
| detailed, its a high level map to guide not a detailed set of
| instructions on how to construct.
|
| These are really good points. I've found that refreshing
| diagrams, even if's a hand drawn update, or modifications, to
| an older diagram for the new person on the team can be valuable
| in identifying what is different and getting a sense for how
| important it may be to redocument (or even refactor) that
| system.
|
| Simply putting dates on diagrams so people aren't guessing is
| helpful. It goes with doing something like automatic labeling
| of content in your wiki that's over a certain age so that
| people are mindful.
| chas wrote:
| I am very fond of using graphviz (https://graphviz.org/) to draw
| the finite state machines that my programs interact with. For
| example, this is a description of the state machine inside the
| Linux kernel audio subsystem, as it was several years ago:
| https://source.chromium.org/chromium/chromium/src/+/master:c...
| You can draw it using 'xdot' for something interactive or with
| 'dot' for a static png or svg file.
| adontz wrote:
| https://plantuml.com/, https://graphviz.org/ and recently
| Graphviz based https://diagrams.mingrammer.com/
|
| I hate Visio so much, I do not hate any other software that much.
| FlyingSnake wrote:
| I love PlantUML as well! I've used it in various capacities
| since 2016 and nothing can beat it's ubiquity. I personally
| find PlantText much better to use than the plantUML provided
| interface though.
|
| [1]: planttext.com/
| adontz wrote:
| I like it, but does it lack autorefresh?
| GordonS wrote:
| Visio is my main diagramming tool, and I have a bit of a
| love/hate relationship with it.
|
| It's a very flexible tool, and you can use it for just about
| any kind of diagram. The ability to use vector images to
| represent parts of the diagram is a real boon for certain types
| of diagram.
|
| But it can be a real PITA to get things sized the way you want,
| positioned the way you want, text labels all aligned correctly
| etc. And if you have lots of layers of shapes, it can sometimes
| be really fiddly to select what you want.
|
| In general, I much prefer to work with text-based diagrams -
| you're not nobbing about nudging pixels, but it also means
| diagrams are much smaller (disk space) and you get diffs.
|
| -- EDIT --
|
| Woah, I hadn't come across diagrams.mingrammer.com, and it
| looks amazing, exactly what I need for non-Visio
| network/infrastructure diagrams!
| GordonS wrote:
| My main diagramming tool is Microsoft Visio, but I also use
| Excalidraw and AsciiFlow when "sketching" rough ideas.
|
| I create architecture diagrams - these show how different
| components fit together, what network boundary they reside in
| etc. I like Visio for these in particular, because I can use
| different images to represent each component - I find it makes
| the diagrams easier to read.
|
| I create "security diagrams", which are basically just a box for
| each significant component, with lines and arrows showing the
| direction of network communication and what protocol and port are
| used. These diagrams also show what kind of authentication is
| used.
|
| I create use case diagrams, to show the actions that different
| roles within the system can perform.
|
| I create very basic inheritance diagrams only to show different
| roles within the system.
|
| I occasionally create action diagrams, if needed to help
| understand decision flows.
|
| I occasionally create sequence diagrams, if needed to help
| understand the sequence of interactions between different
| components/modules/actors.
|
| I very rarely create class diagrams - if I have to do this, it
| basically means the design is too complex (e.g. too much use of
| generics, too much use of inheritance etc).
|
| UML is far from dead, it's just that people don't doggedly churn
| out and maintain every kind of UML diagram for every part of
| every system - they are really useful for explaining a few
| specific parts of systems.
| buro9 wrote:
| * Sequence https://plantuml.com/sequence-diagram
|
| * Use case https://plantuml.com/use-case-diagram
|
| * Object https://plantuml.com/object-diagram
|
| * Activity https://plantuml.com/activity-diagram-legacy
|
| * State https://plantuml.com/state-diagram
|
| Sequence and Activity are my most used - beyond the ones above
| logical architecture tends to be a Draw.io created abstraction
| that ends up in a Google Doc... stuff like this:
| https://camo.githubusercontent.com/f14ac82eda765733a5f2b5200...
| (not one of mine)
| tnzm wrote:
| +1 for PlantUML. Mostly the Sequence diagrams - everything else
| quickly becomes a mess unless you take extra pains to prevent
| arrows from turning into a tangled bundle.
|
| I don't care about the UML vocabulary, just give me boxes and
| arrows and labels and a way to draw them semantically instead
| of some overengineered point-and-grunt GUI.
|
| Now, if anyone came up with a tool that checked that the code
| and diagrams match (no code generation please, the code is the
| source of truth!), now THAT would be lovely.
|
| Just a CLI tool that can be run as part of a CI pipeline, which
| parses the code into an AST, and checks if entity A still has
| properties A.B and A.C, and methods A.D and A.E, and that A.D
| still contains a call to function F - and colors the arrows
| BRIGHT RED if there's a mismatch. That would be enough for
| committing a mental map of a codebase to documentation.
| billfruit wrote:
| PlantUML is great but it renders Statecharts in a non-obvious
| manner.
| ghosty141 wrote:
| I only used the Sequence diagrams because they are super useful
| and the syntax is very intuitive. PlantUML is great
| TeMPOraL wrote:
| Yup, mostly the same set of PlantUML diagrams for me, plus:
|
| * Timing https://plantuml.com/timing-diagram - used it once or
| twice.
|
| I mostly use PlantUML for myself, in lieu of drawing diagrams
| by hand (or pointing device).
|
| My main use cases are a) when I'm toying with some higher-level
| design in my head and want to "see it" in picture form, and b)
| when making notes about the structure of code as I explore
| gnarly areas of a legacy codebase.
|
| In that latter case, I've discovered that my "PlantUML notes"
| follow the code structure close enough that I _should_ be able
| to coax my editor into generating these for me, semi-
| interactively. I might get around to doing that at some point.
|
| Quite honestly, I'm surprised I haven't seen anyone doing a
| generalized "Language Server -> PlantUML" tool for asking
| questions about the codebase and getting responses in graphical
| form. As I mentioned yesterday[0], I find myself in need of
| being able to answer questions like "How does the code get from
| _here_ to _there_? ", and at least some language servers should
| have enough information to be able to give that answer[1].
|
| That time when I spent a whole day building a sequence diagram
| by hand, to document how a certain subsystem is created and
| used in the very heart of the application, paid for itself very
| quickly - but I'd much prefer if it was a matter of couple
| minutes of tuning an invocation like: querypuml
| --type=fromto --from=Foo.cpp:123 --to=Bar.cpp:456 \
| --omit"::utils::*" --omit "SomeClass" \ --omit-
| files "module/irrelevant/*" -o journey.puml
|
| It would make it much easier to _refresh_ the diagram the next
| time I need it for reference.
|
| --
|
| [0] - https://news.ycombinator.com/item?id=26937454
|
| [1] - If a language server supports identifying function calls
| and "jump to definition" (xref), it already has a lazy graph of
| the code structure, so it's a matter of running a path finding
| algorithm on it. Of course this can never be perfect (see also:
| halting problem), but I think a minimum-effort solution would
| cover 80% of cases, and most of the rest could be covered if
| attached to a debugger that records traces.
| flower-giraffe wrote:
| draw.io with embedded plantuml saved as pdf with editable
| source embedded is a fantastic free alternative to Visio.
|
| Plantuml is excellent for some use cases, but not all.
|
| They use kroki to enable embedded plantuml diagrams, you can
| save the whole thing as PDF than includes the source and can be
| edited in draw.io
| deanclatworthy wrote:
| After spending so much time messing around in draw.io and other
| crappy tools, I also settled on using PlantUML recently. Easy
| to commit to VCS, and can easily be shared.
| p_l wrote:
| Similar for me, UML2.0 diagrams done using PlantUML. If I had
| the option, I'd use Enterprise Architect, but it's way too
| expensive to justify - the benefit would be that it keeps a
| separate store of "objects" involved in the project which you
| can refer to from your diagrams.
| etripe wrote:
| Having used both, Enterprise Architect might be more formally
| maintainable, but from a CBA (can't be arsed) perspective,
| PlantUML blows it out of the water. If you use imports in
| PlantUML, you can define your "objects" or even common actors
| or events in their own separate pumls, anyway.
|
| Just my 100% subjective read.
| p_l wrote:
| from what I've seen of an architect working in EA on video
| call, EA allows to more flexibly define objects - and
| doesn't put any preconceptions on their use. With PlantUML
| I'd beware that my common definitions have assumptions
| about being used in specific contexts.
|
| But it's something to test out! :)
| TeMPOraL wrote:
| Definitely worth checking out :). At some point, they bit
| the bullet and included a programming language inside[0].
|
| https://plantuml.com/preprocessing
|
| It's enough to make it easy to organize common chart
| elements into libraries, and even create some DSL here
| and there - the latter being helpful if you're using
| PlantUML for note taking or in lieu of doodling :).
|
| For instance, I got a very good mileage out of "trivial"
| definitions like: !procedure
| call($source, $target, $call) $source -> $target:
| $call activate $target !endprocedure
|
| Forming a mini-DSL that let me turn notes like:
| call("Someone", "SomeoneElse", "FooBar()")
| asynccall("SomeoneElse", "SomeService", "Run(a=42)")
|
| Into a rather large sequence diagram that's also readable
| as text, and possible to auto-generate to some extent.
|
| --
|
| [0] - Which looks like a spawn of an unholy marriage
| between PHP and C preprocessor... but hey, it's a
| programming language.
| thrower123 wrote:
| I end up doing a lot of software infrastructure architecture
| diagrams. The product I work on has a lot of components and
| interacts with a lot of things, and the people we sell it to
| always want that mapped out. Frustratingly, they don't ever seem
| to be able to comprehend the generic diagram, and require it to
| be remapped into their actual infrastructure, which I never have
| any idea about, and am usually at least two Kevin Bacon's away
| from any kind of access to.
|
| Otherwise I do a lot of off-the-cuff statemachine and sequence
| diagrams, I guess you would call them. Very often literally
| scrawled on a napkin and then photographed with my phone.
| FpUser wrote:
| Use case, State Machine, Sequence, ER.
| xupybd wrote:
| Flow charts are huge for me. It's a good way to show a non
| programmer my understanding of a process they have explained. It
| also helps me code a little clearer when the business logic is
| less intuitive.
|
| Also truth tables if I have to work with booleans in excel.
| cies wrote:
| Have a look at http://jjg.net/ia/visvocab , I have not needed
| to use other flow charts since.
| nstart wrote:
| Activity diagrams. I find that they are my go to when I want to
| communicate how something will work. This is when we are
| considering a modification of something that already exists or if
| the idea is new but well defined.
|
| I'll use draw.io usually but if it's to clarify something small,
| I'll just draw it on my notebook and snap a photo of it.
|
| That's what I love about the activity diagram. Communicates a ton
| of information in a form that even if you've never seen it, it
| will be pretty intuitive. And creating it is also super
| lightweight.
| [deleted]
| Nursie wrote:
| Sequence diagrams are about the only thing for a long time.
|
| Otherwise nothing much... random visio-ish things made in draw.io
| or sometimes scribbled out on the fly during presentations using
| a wacom tablet. I tend to prefer words, code snippets and config
| to explain my stuff these days.
| namelosw wrote:
| I use different hand-drawn notations for different purposes -
| they should be intuitive so people would understand without
| learning anything.
|
| The major problem I see in UML is it tried to unify things, but
| in reality, we use diagrams for different purposes and different
| audiences. The same idea could be found in C4.
|
| I don't strictly follow C4, instead, I choose notions I find
| suitable for the audience and context (eg: architecture for tech
| people, domain modeling for domain experts, or just abstract ones
| help myself thinking)
| brucou wrote:
| If we talk about professional use, then Powerpoint (many years
| ago), then Visio (also many years ago), then yEd (by yWorks,
| https://www.yworks.com/products/yed). Then there are a ton of
| specialized open-source tools, with varying quality. Mermaid
| improved a lot. PlantUML has a lot of options, but I would not
| use it professionally. draw.io has also plenty of options, but
| has some usability issues in the frame of a frequent,
| professional use.
|
| For anything UML-related, Enterprise Architect is quite good, but
| boy you better know UML. That ain't user-friendly in the least.
| But super powerful and there are a few more like that out there
| with somewhat limited free versions.
|
| Long story short, my best choice is yEd. And I still reach out to
| Powerpoint every now and then.
| kgilpin wrote:
| We dogfood our own tool, AppMap (https://appland.com/docs/how-it-
| works.html) which records executing code into JSON files and then
| turns that data into interactive diagrams and analysis.
|
| We also think Mermaid is a great project. I want to try the
| entity relationship diagrams next.
| kingsuper20 wrote:
| Boxes and arrows. Occasional pic taken of a whiteboard.
|
| I should write a book on it, maybe give seminars and sell
| training materials.
| ttroyr wrote:
| For front-end to back-end web development, UI/UX-friendly
| collaborative diagramming: https://whimsical.co and
| https://figma.com (new FigJAM tool).
| bewo001 wrote:
| SDL for state diagrams (https://en.wikipedia.org/wiki/Specificati
| on_and_Description_...),
|
| UML seq. charts to develop the SDL state diagrams.
|
| Object Role Modelling for database schema design
| (https://en.wikipedia.org/wiki/Object-role_modeling)
___________________________________________________________________
(page generated 2021-04-26 23:02 UTC)