Figures and Flowcharts for Design Documents

Data Management
#1

Before we decided to focus our long-term planning efforts on a comprehensive update to the design documents, we had a brief discussion about flowchart tools that ended with a recommendation that we use https://www.gliffy.com/, largely (I think) because of its integration with Confluence.

Now that we’re not using Confluence, should we still prefer gliffy for flowchart-like figures? Are there other tools we’d prefer, or recommend that we avoid to ensure the documentation source is cross-platform editable?

#2

We should probably require that whatever graphics we create are SVGs. As for a tool specifically, I don’t know. On the Mac, I’d use Adobe Illustrator or OmniGraffle.

#3

I think the problem with using a desktop tool is making sure that everyone working on the document has access to it. An online tool avoids that problem.

Gliffy for Confluence, which we already have, allows us to save as SVG, so maybe that’s a way to do it.

1 Like
#4

Interesting - the Gliffy Chrome app doesn’t allow me to save as svg (only png and jpeg), so I’d assumed the diagram I just made was stuck in a raster box from which it could never escape. I’ll try the Confluence version.

#5

This is a bit of an extreme suggestion, but we could also consider coding graphics with Matplotlib or D3. For example, my friend made the Daft package for Matplotlib that lets you make flow diagrams (in the context of probabilistic graphical models).

The upside is that it’s easier to connect graphics to data sources, or separate graphic logic from presentation.

The downside, though, is time investment, which probably kills this idea for most purposes.

#6

If we were going to do machine-generated graphs (which I think may be useful at times, but shouldn’t be the only way of doing things), I’d personally prefer to go with graphviz/dot to svg. That worked out pretty well for the JIRA DLP graphs we’ve made.

As a side note, a problem with svg is that Latex doesn’t support it. So at least for LDM-151 I think I’m stuck drawing in gliffy (and committing the native gliffy format), then either exporting it to png within gliffy or exporting svg within gliffy and then using something else to convert that to eps or pdf, and I don’t know of a “something else” that’s cross-platform and readily available.

#7

A quick search brings me to CairoSVG but I haven’t tried it. There is a Mac homebrew package called “svg2pdf” though.

#8

So, a little more research on this reveals that there is an svg package for latex, but it relies on shelling out to inkscape to do the work, and that apparently requires modifying the pdflatex command line. I’m not sure I want to do that, but I figure inkscape is at least as easy to install cross-platform as anything based on Cairo, and I imagine it’s probably somewhat better at doing the conversion.

#9

my interest is in making schematic drawings of systems.

I started using omnigraffle. I think it’s not a first choice because it’s an OS X thing. I also don’t know the answer whether if I use a stencil, where that is stored – IE does the file give me the full editing environment I need.

MY experience with the confluence gliffy is that it’s basic. The strength is that it’s in confluence and that in that environment anyone can edit a figure. I did try to make a “dimarco” type data store as a shape – it’s two horizontal parallel lines. I made a SVG,and ingested it, but I could not change the color, or put a label on top of it as I could with the basic rectangle shape.

I have no concrete suggestion, but I do think there may be something better out there.

I think it’s asking too much, but we may be lucky. One thing I like is that anything that can extract meta data from drawings is potentially useful (but will be difficult to use in practice) – that is really what higher level tooling does EA or “better” EA. (but I guess we are past the point where people want to use that sort of stuff).

#10

That was one think I really liked about using graphviz/dot - I could put arbitrary HTML into the text for shapes (including links to more information) and even add mouse-over text. Given that the output format for that was SVG, it might be that there’s a free SVG editor out there that could do at least that much. Maybe Inkscape can (it’s also a gui). Of course, doing that with graphviz/dot was a lot of work, and isn’t worthwhile unless we’re machine-generating the graphs entirely.

#11

I just realized the overlap of this topic with one of my side projects!,

In case is useful, I developed a little graphic tool which is simple and can be easily extended. It can save the graphs in json files as well as svg (with some caveats) also I wrote a python script to convert from json to dot file.

Check github repo here: https://github.com/mgckind/GraphMaker and live demo here
http://mgckind.pythonanywhere.com/

I used this tool to create the diagrams here: https://confluence.lsstcorp.org/display/~mcarras2/Task+Redesign+Notes

Whenever I can I add some features, right now I’m trying to add sockets.io so diagrams can be synchronized across clients, I’d be happy to discuss more about this side project evolving into something more concrete

1 Like
#12

one more comment. When making the kind of facility documents as we are doing, glifyf does not offer options when lines cross. When working I cliffy I am constantly managing the geometry to deal with line crossings. This is expensive in time, hence in money.

When I look at this I think we need a couple of tools. One I think has to be a rich
well supported tool – I’d hope for a portable omnigraffle, but we need something like
that, even if is pay to play.

I see dot/Graphviz mentioned, I’m a fan, esp to the extent it eliminates fiddling with drawing in a WISIWIG way. I think it definitely has a role. I don’t; see it as covering all the use cases.

#13

flowchart.js could be a browser-based potential solution for generating flowcharts from textual representation. It looks to be in its early days but maybe worth trying.

A more general tool is vis.js which pitch is “Graphviz for the web”.

I have not used neither of them, so I cannot say much more.