Documentation and diagrams

[ville.ilvonen@unikie.com]

Hi,

I asked thoughts on Spectrum documentation improvements some time back on #spectrum. I'd like to improve documentation in terms of architecture (views, description, diagrams) to support communication with people adopting Spectrum in our research/engineering project(s). Of course I can create presentations for such purposes but those are not supporting the project.

There's nothing wrong with asciidoc but as of now it lacks support for diagrams. Another view to diagrams was how we want to create diagrams - writing dsl(diagram-specific-language)-to-diagrams or drawing. Based on our #spectrum discussion I was guided to asciidoc diagram extension - https://docs.asciidoctor.org/diagram-extension/latest/ - so I finally gave it a try last Friday with ditaa - an ascii-to-png-conversion. Long story short - I got it working by adding dependencies to jdk8 etc. but I'm not happy with the result for following reasons:

Limitations: 
- ditaa (and other dsl-to-diagrams) have limited support in either diagram dsl comprehension or available editors. Namely, ascii-based box drawing programs exist (e.g. https://asciiflow.com/#/) but do not directly support ditaa. If ascii-drawings can be modified to ditaa, it's slow, error-prone and worst of all - importing version controlled ditaa-ascii-graph text files back to editors do not work as object imports so in worst case the objects need to be drawn again when one wants to modify the diagrams.
- dsls have learning curves with different slopes. Some are easy, some take domain level understanding (like UML) in addition to dsl but it's there.
- layout algorithms - many cases go quite ok with this but then there's points where the layout algorithms fail miserably with solutions beyond reasonable effort.
- dsls are usually not readable in source format but beyond trivial diagrams always require validation visually

Benefits:
+ Some asciidoc diagram-extension dsl:s (like plantuml, graphviz) work quite ok for both visualizing UML, graphs, dependencies, trees.
+ Focus on content, not presentation - kind of like LaTeX. Though this is limited by tools like ditaa which can get worst of both worlds.
+ dsls can be great for code level views. I've used tool where dsl has been combined into generating the diagrams from code or tree like structures. In fact, there's quite a few such tools to do this with nix-store dependency trees and have been useful in spectrum architecture comprehension.

What I'd like to propose that in addition to aiming at text-to-diagrams we support diagram drawing tool(s) and agree on either png or svg with diagrams.
With diagram drawing tools, we should store the diagrams in editable format in version control (not only png and svg).
My 2 cents would go to https://github.com/jgraph/drawio but I'm fine with others as well - as long as they do not require commercial license.

I'd like to hear thoughts/decisions on this before sending any patches to contribute to spectrum architecture documentation.

Best regards,

-Ville