
Ask HN: What do you use for diagramming in software engineering? - jayliew
What are the popular common tools today for (visually) documenting architecture, component, and interaction diagrams?<p>The core purpose is to facilitate the efficient communication of technical information between software engineers on the team at a high level &#x2F; bird&#x27;s eye view (as opposed to a more granular level line by line comment inside of code).<p>Specifically, something persistent &amp; electronically scalable (not just a temporary whiteboard sketch that goes away!)<p>Not just for a one-off communication, but something long-term so that institutional knowledge stays with the organization, even if people come and go.<p>I&#x27;m thinking out loud here but some kind of product &#x2F; solution that can be baked into a code review process.
======
condiment
I use a combination of tools for visual documentation. Block diagrams and
sequence diagrams together are a pretty effective means of communicating.

For block diagrams that illustrate relationships between components as a sort
of directed graph, I prefer Omnigraffle (on OSX). It's fast and effective,
easy to label boxes, lines, and interactions, and supports exports to pdf and
png for quick sharing. Where omnigraffle falls over is in terms of its
popularity and accessibility. You can't really review the diagram source as a
part of the code review process, and the output diagrams are not useful to the
visually impaired. Popularity is a factor because even if a dev knows some
piece of block diagram software well, it's likely that they know a different
one than anyone else. For that reason, we're not prescriptive about the tool
used on our team, only that some form of block diagram is included with the
documentation for a feature or component.

For sequence diagrams I use web sequence diagrams, for which I hold a
commercial license. These diagrams are great for illustrating different
workflows, with the caveat that we generally need several very similar
diagrams to explain even the simplest features. These also benefit from having
a straightforward text format that can be shared as a reviewable part of the
source tree, and which can be read and edited by the visually impaired.
Sequence diagrams are a more effective tool for demonstrating the veracity of
code against a desired specification than block diagrams are, but
understanding the top-level component layout is generally a prerequisite.

Not sure about the general popularity of either of these, but they've been an
effective toolchain for me so far.

------
jefe_
Omnigraffle is by far my favorite, unfortunately only available on Mac OSX. I
use Windows more lately and struggled to find a comparable offering. Then
discovered Lucidchart
[https://www.lucidchart.com/](https://www.lucidchart.com/) and have grown to
enjoy it quite a lot. It offers common Cisco and AWS networking icons, and has
some nice exporting options and the auto-expanding canvas. There are some
quirks but it is cheaper and in my opinion cleaner than Visio.

~~~
icc97
I've been trying out Lucidchart, I've been finding it frustrating, albeit the
charts do come out looking nice.

Personally I prefer Pencil [0], it suffers from 'another electron app'
syndrome, but I've grown to really like it. It's probably predominantly a UX
tool but it has more fine control over elements than lucidchart does, plus
it's open source.

[0]: [http://pencil.evolus.vn/](http://pencil.evolus.vn/)

------
mlazos
I really like Microsoft Visio for this purpose, it has all of the nice auto
alignment draw features you’d expect and it can really be used for anything
from ultra formal process designs to sketching an idea.

------
ljnelson
Love UMLet ([http://www.umlet.com/](http://www.umlet.com/)), particularly for
the ability to copy and paste diagrams instantly.

In contrast to some others here, I find quick, simple diagrams _immensely_
useful in resolving long, unproductive discussions. They tend to focus
discussions on concepts, ontologies and cardinalities instead of trying to
verbally represent mental models.

------
Discere
I have been using DOT diagrams a bit recently -
[https://en.wikipedia.org/wiki/DOT_(graph_description_languag...](https://en.wikipedia.org/wiki/DOT_\(graph_description_language\))
\- I like it because I can put into source control too

~~~
Jtsummers
PlantUML is a cool tool that will generate a lot of the types of diagrams
programmers and system designers might like to make and see. Plain text
descriptions of the diagrams turned into images. Some of them you could do
directly in DOT syntax, but not all or not as easily.

[http://plantuml.com](http://plantuml.com) (I do, however, seriously dislike
how many ads are on the site for this thing)

~~~
krueger71
Good tool that is often enough. Text-based means version control. I'm using it
via a plugin in Visual Studio Code. Very lightweight solution.

------
jillesvangurp
I use Umlet in the rare case where I actually need to produce a diagram. Umlet
has a nice delarative syntax and allows you to create complex diagrams with a
minimum of fuss. Which for me is the key point because Imho, most diagrams are
completely pointless. The less time spent on them, the better. But sometimes
you just have sit down and waste some time on them.

I don't get a lot of value out of diagrams for the work it takes to produce
them.

------
digikata
I generally use either a wiki page (if there is an agreed upon common wiki),
or a short memo document. A wiki is nice because it's easy to include a URL
into a commit.

The diagramming tool is a minor consideration except it should be easily
editable by someone coming along later. The important thing isn't the tool,
but that there is a common, known place to look and collect the info for the
team. It could be as simple as a shared folder as long as everyone agrees.

In general, I write and try to encourage "tech memos" that are short of
capital-D official, complete Documentation, and instead focus on capturing the
high-level view of some scoped aspect of the total system. Memos that cover
say a walk-thru of one type of operation through the entire system, how a
single feature interacts with the larger system, or a tricky bit of analysis,
logic, or assumptions on some key point; all tend to be popular reading.
Whiteboard pics are often included just for convenience if needed too.

------
mehrundmehr
I've turned many people onto OmniGraffle. I'm quite the power user.
Fortunately it's very well-made software that rewards power users well. I have
the full version (the most expensive one) but I use it so much that I feel
it's totally justified paying hundreds of dollars for. I also use it for light
wireframing instead of Sketch.

------
fundamental
It depends on the exact problem and how long term you need to documentation to
exist. For a lot of things physically drawing out diagrams is great. It's fast
to do and based upon the questions you get it's easy to draw more detail on
the area being discussed.

For more long form docs I tend to use a mix of LaTeX's TiKZ (though I used to
use PSTricks) for block diagrams and for a somewhat faster workflow I've used
some of the diagramming tools which integrate nicely into an asciidoc based
document. That can be graphviz, blockdiag, seqdiag, etc (
[https://asciidoctor.org/docs/asciidoctor-
diagram/](https://asciidoctor.org/docs/asciidoctor-diagram/) has a decent list
of some of the options).

With any option it's easier to quickly sketch something out than it is to have
some clear well organized diagrams which don't need any external context to
understand.

~~~
jayliew
Something long term, that you can use to onboard new employees. They can just
look a the visual and reconstruct a mental map of how things are laid out at a
high level, without this institutional knowledge having to be passed around
verbally and subject to the quirks of human memory (and subject to individuals
possessing this knowledge potentially leaving the team!)

------
ttd
I'll put in a plug for an offline diagramming tool that I created, Vexlio
([https://vexlio.com](https://vexlio.com)). It has some neat features like
embedded LaTeX equation editing, nice snapping, and a program mode (so you can
draw diagrams in Lua code if you prefer that to mouse work).

~~~
zxexz
I love Vexlio! I use the Windows version whenever I'm doing diagramming on
Windows.

As somebody who predominantly uses Linux, I was wondering if you have Linux
support on your roadmap? I'm rarely actually in a situation where I could use
Vexlio on OSX or Windows, but of you had Linux support I would literally be
using it daily (and I'm sure I'm not the only one).

I used to use it in Wine, but it took a lot of finicking to get it working and
behaviour was just a little too nondeterministic when it worked.

~~~
ttd
Thanks, I'm glad you like it! I should experiment with Wine to see if any of
the finicky behavior is something I can fix on the Vexlio side. There has been
a lot of interest in a native Linux version, and it is on the longer-term
roadmap. Unfortunately it is a fairly significant undertaking, so it will most
likely be a while.

~~~
zxexz
Thank you for the response :)

When I get some spare time I can send you the details on what I had to do to
get it (barely) working.

------
bbulkow
Honestly, I think we use Google docs draw more than anything else. I don't
love it, but it is group editable, has a permission system, good comments, and
we can just paste urls in tickets and design documents. Many engineers simply
use the draw tool in confluence, too. Trying to draw in markdown doesn't work,
obviously.

------
cdnsteve
Gliffy Diagrams and Draw.io are two that I'm using. Draw.io has a lot more
features, export options, etc.

------
makimat
Softagram was mentioned once here as a solution to keep your diagrams up-to-
date automatically. I happen to know it quite well as I am their lead
developer ( --> take my words with a grain of salt ;).

It's surprising though how many are still bound to the idea that if you want
diagrams for documentation, you'd better get a good drawing tool and draw them
yourself. While manual drawing might give more flexibility, the burden of
creating and maintaining those diagrams is often too much in the agile
projects we work with. I suggest you all take a test drive on Softagram. Just
go to softagram.com, register for a free trial, add your git repo and off you
go. I'd be delighted to hear if you like it or not.

------
qpiox
Modelio is open source and has one of the best support for UML2. I have been
using it for several years. It also has jython scripting support to write
automation for mass modifications in large models. I have managed to learn how
to use jython to create a script to automatically generate java source as
hibernate jpa entity classes just the way i like it in just one day. This was
made much easier with the builtin metamodel browser so that you learn how your
whole project model is constructed internally.
[https://www.modelio.org](https://www.modelio.org)

------
ezekg
I've started using Monodraw[0] recently for creating technical diagrams and
really enjoy it.

[0]: [https://monodraw.helftone.com](https://monodraw.helftone.com)

------
badhombres
A whiteboard and imagination from the oral documentation. It's actually
something I'm working on getting my team to fix sense I got here. I'm
interested in this topic.

~~~
jayliew
I use whiteboarding too, but yeah, it's basically a snapshot / dump of
institutional knowledge that resides in an individual's head. Updated my post
to mention that I'm looking for something electronic / scalable

~~~
fundamental
Depending upon the situation it can make sense to just take a picture of the
whiteboard with a camera (or use a smartboard) and save that image somewhere.
At that point the diagram isn't 'editable' per-say, but that can still be
great solution.

~~~
jayliew
I definitely prefer something editable. The use-case is if someone improves
the system, then this visual diagram needs to be updated.

I want to avoid the situation where the left hand doesn't know what the right
hand is doing. Any person on the team doesn't have to go hunt down the person
who knows the system, but can just look up the diagram at a high level and
know where to start.

------
gregatragenet3
Gliffy as part of confluence (save often!) Dia for personal projects. Would be
interesting to see what folks suggest re tools that are code-review friendly.

------
elango
Draw.io is a gem, with gdrive integration, it is easy to collaborate, embed
and cross reference diagrams. We tried creatly before locking on draw.io

It is free btw

------
dirtyaura
Just benchmarked a couple of web-based diagramming tools: LucidChart and
draw.io

Both work, I ended up choosing LucidChart and we are now testing it with the
team

------
quintes
I use lucidcharts a little, it's pretty good for component models.

Primarily though I use sparx enterprise Architect. I've been told it's
outdated, others don't like the ui, but honestly all my models are in one
place, including wire frames and use cases. I enjoy use it. It's roadmap
creation support I do not like, like a poor Gantt (at least last time I tried
it)

------
imhoguy
For manual diagrams Dia or Gliffy with Confluence. Unfortunatelly manualy
side-made diagrams get out of sync quickly as codebase is a live thing.

When the code is primary source of truth it is better to use some on the fly
visual analysis. In my current place we use Softagram to mainly analyse bird
eye level changes at reviews, but it also helps during staff onboarding.

------
scruple
Mostly draw.io but I am very keen to check out Pencil the next time I need to
diagram something based on what I've seen.

~~~
jimpudar
We use Confluence for our Wiki and have draw.io integration. This works really
well as all our diagrams are editable by anyone forever.

I used to use Visio on Windows and had an excellent experience.

------
pcx
Draw.io is pretty great. I've started trying out RealtimeBoard.com, but
haven't really got a hang of it yet.

------
curyous
[https://www.planttext.com](https://www.planttext.com)

------
samlittlewood
[https://www.yworks.com/products/yed](https://www.yworks.com/products/yed)

[http://casual-effects.com/markdeep/](http://casual-effects.com/markdeep/)

------
cpburns2009
When I left my previous employer several years ago I documented our
infrastructure using Dia [1].

[1]:
[https://en.wikipedia.org/wiki/Dia_(software)](https://en.wikipedia.org/wiki/Dia_\(software\))

------
joaofs
Quite surprised no one suggested
[https://structurizr.com/](https://structurizr.com/). It uses C4 diagramming
approach. Quite useful for a more lean approach to docs.

------
flarg
I've used PlantUML for ages and that's good, but Sparx Enterprise Architecture
is my goto these days because it works as a database of components as well as
documentation authoring and publishing tool.

------
ifend
yEd is my go to editor. Works on all platforms and is free.

[https://www.yworks.com/products/yed](https://www.yworks.com/products/yed)

------
bitL
Mainly draw.io, tried also Lucidchart. In addition attempted to use Dia on
Ubuntu and long before that Visio of course.

------
chrisgoman
[https://mermaidjs.github.io/](https://mermaidjs.github.io/)

------
BerislavLopac
[https://www.lucidchart.com/](https://www.lucidchart.com/)

------
wwwhizz
I like draw.io for most diagrams. Visio is good too, but I think it is too
expensive.

------
a_lifters_life
lucidchart.com - been using for ~5 years now, really great s/w. And no: I'm
not a paid sales rep, but a happy customer.

------
siruncledrew
draw.io. It has nice AWS add-ons too.

------
senatorobama
Asciiflow.

