From: [email protected]
Date: 2017-09-11
Subject: Diagrams from Text with PlantUML

Visual  models are an important tool for analysts because they pro-
vide another way to look at and think  about  the  topic  at  hand.
Written  documentation  is good and necessary, but the written word
is subject to interpretation and misinterpretation.  Visual  models
and diagrams provide another way to communicate and interpret crit-
ical information. Examples of visual models include process  flows,
entity-relationship  diagrams,  wireframes,  and use case diagrams.
Maps and timelines also  help  us  visualize  information.   During
meetings, I often sketch diagrams on a whiteboard or with a pen and
notepad. It's a great way to summarize information and  check  your
alignment. Digital diagrams are often easier to read, maintain, and
share.

There are many tools available to help you create diagrams. Most of
these  give  you  a  drag-and-drop interface that lets you visually
place and manipulate objects in the diagram. While this type of in-
terface  promises to make diagramming quick and painless, there are
downsides. Manipulating objects visually can take a  lot  of  time,
especially  as  the  size  and complexity of the diagram increases.
Making changes to a diagram often requires you to tear your diagram
apart and then put it back together after you've added, changed, or
removed elements. It can also be a challenge  to  allow  others  to
make  and share changes to a diagram you've created. After a while,
it may be easier to throw it all out and start over!  The  ease-of-
use promised by the WYSIWYG interface fades quickly.

PlantUML[1]  is  a  tool  that  lets you create diagrams from text.
This can be a real advantage over WYSIWYG interfaces for a few  key
reasons. Working this way can be faster because there is no search-
ing for, placing, sizing, and manipulating  visual  elements.   Any
text  editor can be used to write PlantUML code. Text can be easily
modified, shared, and version controlled. The syntax used by  Plan-
tUML  provides yet another way to think about the idea being repre-
sented in the diagram -- by considering each element on its own, we
can  give  each  one  our  full attention. When you are done making
changes to your PlantUML text file, you use the  PlantUML  software
to render your diagram. PlantUML can be downloaded and run locally,
or you can use the web-based service at PlantUML.com[2].

I'll admit that there  are  times  when  PlantUML  isn't  the  best
choice. The diagrams it generates are not the most beautiful things
I've ever seen. For wireframes, especially, I would go back to  us-
ing something like LucidChart. PlantUML also has limitations around
the size of its diagrams. It's possible to divide  images  up  into
multiple  pages but, for very large and complex diagrams, other so-
lutions, like Visio, might be preferable. For low  to  medium  com-
plexity  diagrams,  PlantUML  is  an interesting tool that lets you
create diagrams without pixel-pushing, and it  makes  updating  and
sharing diagrams easier than performing surgery with a mouse.

[1]: http://plantuml.com
[2]: http://plantuml.com/plantuml