Ask HN: What diagrams do you use in software development?

https://news.ycombinator.com/item?id=26940593

by cies • 5 years ago

241 155 5 years ago

news.ycombinator.com

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

joelschw• 5 years ago

dbdiagram.io for ERDs these days:

https://dbdiagram.io/home

sidcool• 5 years ago

C4 model helps for existing architectures. I use Mural for that.

cies4• 5 years ago

Did not know of this, thanks for mentioning. I think this can help me to make my architecture diagram less loosely defined.

cies4• 5 years ago

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• 5 years ago

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/

linkdd• 5 years ago

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.

Hypergraphe2• 5 years ago

+1, I use this too.

marton78• 5 years ago

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.

smoe• 5 years ago

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• 5 years ago

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.

victor963• 5 years ago

I also love the simplicity and structure of the C4 model. I'm currently working on a tool at http://icepanel.io which implements the concepts that are talked about.

buro9• 5 years ago

* 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)

p_l2• 5 years ago

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• 5 years ago

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.

deanclatworthy• 5 years ago

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.

tnzm• 5 years ago

+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.

billfruit4• 5 years ago

PlantUML is great but it renders Statecharts in a non-obvious manner.

flower-giraffe• 5 years ago

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

ghosty141• 5 years ago

I only used the Sequence diagrams because they are super useful and the syntax is very intuitive. PlantUML is great

TeMPOraL2• 5 years ago

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.

xupybd• 5 years ago

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.

cies4• 5 years ago

Have a look at http://jjg.net/ia/visvocab , I have not needed to use other flow charts since.

Nursie• 5 years ago

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.

laci27• 5 years ago

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:)

splittingTimes2• 5 years ago

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• 5 years ago

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

pjmlp• 5 years ago

UML and Entity Relationship ones.

marvinblum• 5 years ago

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.

rwoerz• 5 years ago

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.

pydry2• 5 years ago

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• 5 years ago

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.

pydry2• 5 years ago

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.

globular-toast2• 5 years ago

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.

grammarnazzzi• 5 years ago

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

globular-toast2• 5 years ago

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• 5 years ago

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

splittingTimes2• 5 years ago

Simple Diagrams is great for this. Can vouche for it.

===

https://www.simplediagrams.com/

Pinus• 5 years ago

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• 5 years ago

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• 5 years ago

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.

bostonsre• 5 years ago

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.

billfruit4• 5 years ago

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.

alfiedotwtf• 5 years ago

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• 5 years ago

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.

cies4• 5 years ago

And beyond the UML diagram family? ERDs maybe?

tluyben2• 5 years ago

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• 5 years ago

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• 5 years ago

Most designs can't be planarized that easily, so I don't use diagrams.

itsArtur• 5 years ago

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 :)

Hypergraphe2• 5 years ago

Hi, there are several draw.io plugins available on github do use C4 in draw.io if you are not already aware of this.

NicoJuicy• 5 years ago

PlantUML had support for c4

victor963• 5 years ago

We're currently working on tooling at http://icepanel.io which supports the C4 model. Please reach out to us if you'd like to chat about this, we'd love to hear your thoughts.

pintxo• 5 years ago

Most often used are process diagrams: My preferred tool here is the great text editor based: https://sequencediagram.org/

Rochus• 5 years ago

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/

Gehinnn4• 5 years ago

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...).

notRobot• 5 years ago

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• 5 years ago

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.

kwanbix• 5 years ago

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.

tda• 5 years ago

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• 5 years ago

Could you add a link to your extension please ?

Gehinnn4• 5 years ago

You can find it here: https://marketplace.visualstudio.com/items?itemName=hediet.v...

Like draw.io, it is open source! (https://github.com/hediet/vscode-drawio)

jimbob45• 5 years ago

Came here to say this. It’s free and it does a great job.

gonzo41• 5 years ago

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.

kenoph• 5 years ago

Just FYI: draw.io uses SVG foreignObjects for styling the text in the diagrams. That means that to get a proper rendering of the resulting SVG you need to look at it in a browser. If not, it has a fallback text element, but you lose the styling. I lost many hours due to this :/ other than that, I like it a lot

Gehinnn4• 5 years ago

Sadly, this is a known problem. Theoretically, you can use Chrome headless to render such SVGs into PDFs.

avereveard• 5 years ago

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

yrgulation• 5 years ago

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.

roland35• 5 years ago

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.

oneplane• 5 years ago

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.

fsloth• 5 years ago

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.

adflux• 5 years ago

Visio. I like the large amount of styling options, installable Azure component packs.

nablaone• 5 years ago

* 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.

stared• 5 years ago

TikZ:

- http://www.tcs.uni-luebeck.de/downloads/mitarbeiter/tantau/2...

- https://texample.net/tikz/examples/tag/diagrams/

- https://www.overleaf.com/project/5c73f8d11e30574803429a04

captaincaveman• 5 years ago

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• 5 years ago

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.

adontz2• 5 years ago

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• 5 years ago

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/

adontz2• 5 years ago

I like it, but does it lack autorefresh?

GordonS2• 5 years ago

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!

nstart• 5 years ago

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.

hantusk• 5 years ago

I use mermaid: https://mermaid-js.github.io/mermaid/#/

And excalidraw: https://excalidraw.com/

keraf• 5 years ago

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/

heyoo• 5 years ago

Rich drawings in draw.io.

Sequence diagrams in PlantUML (using the awesome VScode extension)

GordonS2• 5 years ago

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.

bayindirh• 5 years ago

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.

namelosw• 5 years ago

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)

kgilpin• 5 years ago

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.

coward76• 5 years ago

Sequence diagrams, state transition diagrams, and network diagrams provide the most value to the development teams I have been working with.

hatchoo• 5 years ago

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.

FpUser• 5 years ago

Use case, State Machine, Sequence, ER.

anyonecancode• 5 years ago

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.

billfruit4• 5 years ago

Statecharts often provide a mote complete picture of behaviour than sequence diagrams.

viraptor• 5 years ago

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)

tootie• 5 years ago

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.

pezo1919• 5 years ago

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.

ta988• 5 years ago

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.

simonsarris• 5 years ago

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.

mzaccari• 5 years ago

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/

TeddyDD• 5 years ago

Sometimes I use DRAKON. It's useful for untangling complex algorithms.

[1] https://drakonhub.com/en/drakon

thelastinuit2• 5 years ago

effing loving that tool.

lugu• 5 years ago

+1 It forces me to express in the most simple way the intention behind the code.

thrower123• 5 years ago

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.

crispyambulance• 5 years ago

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.

jjuhl• 5 years ago

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.

astatine• 5 years ago

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.

mr_tristan2• 5 years ago

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• 5 years ago

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.

mr_tristan2• 5 years ago

What's important here is that I'm using diagrams mostly in high level, explanatory documents.

For example, the decision nodes will be somewhat vague, e.g., "Does event have good location data?" The details of that question are actually very complex, covering multiple fields from different data sources. But the gist is very much "if we don't know it, we're going to then hit this location subsystem". This is in a processing chain that's pretty complex, so, it's just kind of a basic guide.

Most of the consumers of these docs are often engineering managers who want a picture of the system, but aren't performing real engineering analysis.

I don't use them for detailed technical analysis. Usually, that just involves code.

I find dataflow diagrams can be useful, but even those can be overwhelming, depending upon the audience.

Ultimately, I don't think you can just talk about diagramming without the context in which you're using the diagrams. I rarely use diagrams with technical reference documentation these days. I use them with high level explanations or tutorials.

billfruit4• 5 years ago

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.

agentultra• 5 years ago

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/

hcarvalhoalves• 5 years ago

- 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.

thelastinuit2• 5 years ago

https://www.nomnoml.com/

http://chartmage.com/index.html

https://swimlanes.io/

https://dbdiagram.io/home

irrational• 5 years ago

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• 5 years ago

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.

victor963• 5 years ago

Here's one of these I found recently: https://dbdiagram.io/

kingsuper20• 5 years ago

Boxes and arrows. Occasional pic taken of a whiteboard.

I should write a book on it, maybe give seminars and sell training materials.

bewo001• 5 years ago

SDL for state diagrams (https://en.wikipedia.org/wiki/Specification_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)

jifii3• 5 years ago

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!

ttroyr• 5 years ago

For front-end to back-end web development, UI/UX-friendly collaborative diagramming: https://whimsical.co and https://figma.com (new FigJAM tool).

regus• 5 years ago

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?

bsldld• 5 years ago

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

blumomo2• 5 years ago

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• 5 years ago

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.

blumomo2• 5 years ago

There’s good tooling for FMC: pen&paper and white boards ;-) FMC is so easy, you can draw it everywhere.

drittich• 5 years ago

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.

_ZeD_• 5 years ago

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)

49yearsold• 5 years ago

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.

EB66• 5 years ago

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.

brucou• 5 years ago

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.

kazinator• 5 years ago

While UML's inheritance diagrams have been dead to me for a long time, I still like the sequence diagrams.

Common sentiment, I suspect.

motohagiography• 5 years ago

I use Sankey diagrams with D3.js for a lot of security architecture work.

benfrancom• 5 years ago

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.

vaughan• 5 years ago

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.

jerome-jh• 5 years ago

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.

bmn__• 5 years ago

We visualise certain data structures (DAGs and trees) for debugging and documentation with https://graphviz.org (EPL) and https://yworks.com/yed (proprietary, freeware).

bullen• 5 years ago

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

mbar84• 5 years ago

https://mbarkhau.keybase.pub/asciigrid/

vladojsem• 5 years ago

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!

kcartlidge• 5 years ago

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.

8note• 5 years ago

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

emmanueloga_• 5 years ago

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

chas• 5 years ago

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.

Graffur• 5 years ago

draw.io - it's the best and it stores locally

flarg• 5 years ago

Archimate for high level architecture, uml for more detail, and masala diagrams (that's what we're calling them right?) in ppt for marketecture

markmanks• 5 years ago

For quick sketches of architectures, try https://isoflow.io (a tool I'm building). It's designed with a strong visual language in mind.

madorb• 5 years ago

plantuml for sequence diagrams, lucid chart for system cartoons

vinhnx• 5 years ago

Monodraw [https://monodraw.helftone.com/]

I really like it simplicity in creating charts

spatx• 5 years ago

Mostly architecture diagrams, data flow diagrams, flow charts, sequence diagrams and ERD. Mostly they are used as an accompaniment for the brainstorming and design discussions and, in some cases, to serve as easy reference for future. We mostly use draw.io and Visio as the diagramming software in our teams.

Ask HN: What diagrams do you use in software development?

Related Stories