Generating legal diagrams from text
more efficient diagram-making with Mermaid
The law is very text-heavy. It is common for legislation and case law to set out complex concepts and complicated procedures in prose, which can be tedious to read and difficult to understand.
Quite a bit of the value-add of a lawyer is reading all that prose for you, and distilling it down into a quick summary that is relevant to your situation. Sometimes this summary is in prose (but shorter and more punchy prose), and sometimes the summary includes diagrams. Such diagrams can be incredibly helpful in conveying the relationship between concepts and processes.
These diagrams are generally created via PowerPoint or Word.1 Lawyers use PowerPoint and Word for diagram-making for good reasons:
- they use these programs every day and are innately familiar with how to use them
- the learning curve for these programs is gentle. The drag-and-drop, WYSIWYG interface makes it easy for anyone to quickly start designing diagrams one text box or callout at a time. SmartArt makes it easy to make the diagrams look decent (albeit somewhat cliché).
Diagram-making via these programs works pretty well, but there are in my view, one key disadvantage: creating is easy, but modification is difficult.
As anyone who has had to modify a diagram on PowerPoint or Word will know, after changing the size of one shape, you then have to manually resize all the surrounding shapes accordingly. If you re-arrange a shape or add a new one, you have to shift all your related shapes accordingly.
If you want to increase the size of one shape and insert a new shape in between, you have plenty of re-arranging to do.
And if you have your perfect diagram, but for some reason need it to be narrower or shorter (e.g. so you can squeeze some explanatory text by the side), all hell breaks loose and you will need to both resize and re-arrange everything.
SmartArt ameliorates this problem by allowing you to simply edit text versions of the diagram, whereupon it takes care of all the resizing and re-organisation for you.
But it doesn't go far enough. To preserve the gentle learning curve associated with PowerPoint and Word, the standard editing method is preserved and it's very easy to unknowingly break out of text-based generation and enter a hybrid world where the diagram is partly the product of text-based generation and partly the product of your manual edits. If you shift the position of one of the shapes or change its size, SmartArt will try to adjust the others accordingly, but subsequent diagram-editing will not be as straightforward because the formatting will be inconsistent and there is no easy way to return to pure text-based generation.
SmartArt is also limited — it only allows generation of diagrams that conform to its rigid templates. For instance, it is not possible to label the arrows above without doing it manually, or to add a new arrow going upwards such as in the following diagram:
Generating diagrams from text overcomes the difficulties in modifying diagrams and also makes creating diagrams quicker and more efficient. Some front-loaded investment in learning is needed considering the steeper learning, but this is more than repaid in terms of time saved for anyone who expects to be creating diagrams for years to come.
One popular markup language that allows text-based generation is Mermaid. It has a fairly straightforward syntax that supports creation of complex diagrams and is far more flexible than SmartArt.
For example, the following text:
flowchart TD T[Trademark application]-->F[Formalities examination] F-->S[Substantive examination] S-->O[Office action]
will generate the following diagram:
The syntax is simple: just draw arrows between text using dashes and angular brackets. It is readable on its own without the generated diagram.
With text-based generation, it is trivial to add new shapes and text. Mermaid will automatically re-arrange the shapes in a sane manner. For example:
flowchart TD Application[Trademark application] Application-->Formalities Formalities[Formalities examination] Formalities-->Substantive Substantive[Substantive examination] Substantive-- objection -->OA[Office action] OA-- response -->Substantive OA-- objections overcome -->TMJ[Published in Trade Marks Journal] Substantive-- no objections -->TMJ TMJ-- no opposition -->Registration[Mark is registered] TMJ--->Opposition[Opposition proceedings] Opposition-- opposition unsuccessful -->Registration
There is much to be said for using Mermaid to create diagrams in legal work. No need to bother with sizing or placing each node — Mermaid does it automatically for you. All you need to do is specify the content and relationship between each node. And Mermiad is highly customisable. You can have sections with different orientations, adjust the length of the connecting lines, use different shapes besides squares, and even include Font Awesome icons.
That said, I realise any transition will be tricky because PowerPoint and Word will continue to remain industry standards for the foreseeable future. Even the new Supreme Court Practice Directions 2021 refer to "Microsoft Word format".2 As an interim solution, one way to use Mermaid whilst continuing to work primarily in PowerPoint and Word is to use the Mermaid Live Editor web app that generates diagrams from mermaid text in your browser. The diagrams can then be exported as PNGs or SVGs and included in the relevant PowerPoint and Word documents.
One major flaw with the interim solution above is that there will likely be doc-rot. Diagrams will become more difficult to maintain if they are generated via Mermaid text that is not contained in the same file. The Mermaid text is likely to be lost or misplaced, and the diagram will have to be generated from scratch.
One solution to this I have in mind is to embed the Mermaid text (perhaps compressed) into the diagram file directly (i.e. the SVG or PNG), in an area that will be ignored by most PNG and SVG viewers, but which can then be read by a modified version of the Mermaid Live Editor web app.3 Essentially, you would then be able to drag a PNG image of a Mermaid file onto the editor, edit the Mermaid text, and re-export it.
In the longer term, however, I think there should be a Mermaid PowerPoint and Word add-on that allows you to edit Mermaid diagrams within the relevant programs, in-place. Perhaps I'll build this at some point.
Aside: I refer to the legal industry above because that is an area I am familiar with, but I believe much of the above applies equally to other professions that involve office work. Consultants, accountants, and other office-workers will likely also reap similar benefit from learning to generate diagrams from text instead of using PowerPoint and Word.
- Or more rarely, Google Docs or the macOS equivalents, Keynote and Pages↩
- para 56(12)↩
- It may be possible to store the text in the file metadata, which would simplify the implementation, but this would come at the cost of file size and some risk that the metadata will be stripped when embedding or sending the file (e.g. WhatsApp strips metadata of images).↩