Let's start with the most important stuff.
Here is a quick check list in order to verify solution maturity:
- Can a result be auto-generated for any given piece of code?
- Can it be continuously updated without any need in additional "adjustments"?
- Does the solution support deterministic and simple layouting?
- Can it visualise a simple switch-case with three or four options?
- Does it allow to handle versioning and visualise difference between two versions?
These "requirements" might look like an overkill, but without that users eventually will be forced to deal with the code and all fancy visualization tools will become useless. Anyway, let's check a free form flow-chart idea. Here is 8 years old free form DSL structure visualization:
Let's check it:
- It can, but it might be really hard to layout items properly, so user will need to adjust the structure.
- Potentially yes, but it is highly likely layout will be broken.
- No, there will be many ways to layout nodes and you'll need to investigate some special articles (like, for example, Drawing rooted trees in linear time by
Christoph Buchheim, Michael Junger and Sebastian Leipert) in order to make sure user will not spend seconds waiting for a structure to appear.
- No. Layout is complex, so it will be really hard to compare current and previous structures.
Below I'll try to summarise my experience. I'm doing that just for fun, so feel absolutely free to ignore this answer.
Example above shows visualization of pretty complex network protocol decoding logic. Despite the fact it is simple it still provides decent high-level overview and simplified navigation. The problem is it requires user to properly layout elements in order to make the whole structure readable.
- Lesson 1: Pretty much all flow chart examples looks readable because they are simple. Real-life structures are way more complex, so corresponding flow-charts will be complex too and lots of additional tricks will be needed to help users read those structures.
Lesson 2: Users do not like/want to spend their precious time doing stupid layouting.
Lesson 3: A layout, created by a user, should not be altered by a system.
So there is pretty important conclusion: avoid bothering user with the layout. Also there are several quite valuable rules:
Communicating Design: Developing Web Site Documentation for Design and Planning
You'll find lots of interesting hints in that book, but I would like to highlight the importance of choosing proper direction. Naturally you can use canvas, draw anything you want and let user drag it, but it is better to simplify everything and follow usual scroll pattern.
Check D3.js Drag and Drop, Zoomable, Panning, Collapsible Tree with auto-sizing.
BTW, there is classical and simple flow chart representation called Nassi–Shneiderman diagram
Modern implementation of such approach might be quite useful, but it depends. I bet it does not look very straightforward and intuitive from the very beginning :)
Flow chart is not the only approach. Let's look around for a second.
There are a lot of different solutions already available, just check visual programming
I would suggest to check:
No magic there, if you have initial complexity you'll definitely see it later:
Enhancing flow chart
Wikipedia has simple flow chart example. I will use it to demonstrate proposed approach.
I'm not going to present anything special. Just a simple idea how to simplify rendering and make it uniform and flexible.
Please note, this is something like a wire-frame just to illustrate the idea. Elements are clean and readable. It is easy to identify flows and navigate through them.
Rendering is deterministic and pretty straightforward. Basically it is all about columns and rows:
Switch-case construction is possible
Execution flow is easily traceable
Elements can be grouped
Columns and rows can be folded
In some cases "flow stretching" might be required
In some other cases flow stretching can be used to enhance readability.
Versioning and diffs
Having deterministic and stable layout it is pretty easy to compare two different versions of the same algorithm.
Moreover, we can use "flow stretching" in order to make diffs highly readable and mimic similar tools used for textual sources:
- Can a result be auto-generated - yes, easily
- Can it be continuously updated - no problem at all.
- Deterministic and simple layouting - yes, no manual adjustments are required
- Can it visualise a simple switch-case - yes
- Does it allow to handle versioning and visualise difference - yes it does. BTW, three way diff is also possible.
Almost for any complex language simplified DSL can be introduced. I would say it should be much easier to design simplified language on the top of the current one.
Having that you can get everything mentioned above virtually for free.
Thanks a lot of the question :)