Non-WYSIWYG diagrams on the wiki

Diagrams are constantly used in technical documentation to illustrate a thought - many facts are easier to present graphically than text.

I want to talk about how to insert charts on wiki pages (the word wiki in this article is meant exclusively by MediaWiki ). The standard approach - storing charts in files inside the wiki itself - has its drawbacks; about them - under the cut. I tried to use Graphviz - a tool that draws graphs from given data. Here is the source of the image that started this article:
')

digraph A {
Feedback -> New_Assigned [dir="both"];
New_Assigned [label="New / Assigned"];
New_Assigned -> Rejected [dir="both"];
Reopen -> Rejected;
Reopen -> New_Assigned;
New_Assigned -> Resolved -> Testing -> Approved -> Closed;
Testing -> Closed;

{ rank=same; Feedback; Reopen; }
{ rank=same; Resolved; Testing; Approved; }
}

The problem of cross-platform and "where to store the source"

Programmer Vasya drew a diagram in his beloved Omnigraffle, saved it in png and uploaded it to the wiki. A week later, a new component was added to the project architecture, and PM Katya wanted to edit the diagram. But she cannot do it right away, because a) Vasya is sick, and the source code lies only on his machine; b) Katya uses Windows, where omnigraffle somehow does not work.

Vasya could upload not only png into the wiki, but also the source code, and put links between the files - the solution is not very elegant, but it works. Cross-platform problem is not so easy to solve.

Look at a less natural non-WYSIWYG solution.

Graphviz on wiki

Graphs in graphite are described by text - as in the example given at the beginning of the article. Strengths of the graph account:
- simple enough syntax;
- he himself thinks about how to arrange the elements of the diagram in the most optimal way - for example, minimizes the number of intersections of arrows (aka graph edges);
- the diagram is always easy to edit, and the layout automatically adapts to the new data;
- cross-platform, of course - graphviz binaries are distributed for Windows, MacOS and many Linux assemblies.

An extension for the wiki adds a <graphviz> , inside which you can write chart code. The extension installation takes several minutes: you need to download the archive (the links are given below), unpack it into the extensions folder, and add the line connecting the plugin to LocalSettings.php. For charts to be rendered, there should be a graph view on the server where the wiki is running.

Result

What we get at the cost of small efforts:
- You can draw and edit charts without installing additional software;
- each diagram has a transparent source;
- diagrams can be “drawn” even on an iPhone.

Minuses

- the participants of the workflow need time to master the syntax of the graphviz;
- graphviz is not suitable for those cases when you need to manage the layout manually - you need to understand that this is not a WYSIWIG editor, and that absolutely any chart cannot be represented in it;
- there should have been one more minus for concurrency, but I could not find it; maybe the reader will suggest something.

Killer feature

I did not want to list in detail the features of the graph account, but I really want to mention one particular feature. Any graph node drawn with a graph can be turned into a link! This is incredibly convenient if the diagram describes the interaction of the components of a complex application, as it provides connectivity between the diagram and information about the components. For example, by clicking on the square in which “Storage” is written, the reader will immediately go to the page describing the data storage.