Decide on a standard diagram tool for the Knative project

[abrennan89]

Desired Outcome

Decide on a standard diagram tool for the Knative project

For...

Contributors, developers, docs peeps, anyone who needs to create diagrams

So that...

Diagrams for the website will have a consistent look and feel, and contributors can collaborate better because everyone is using the same tool.

Additional Info

[omerbensaadon]

I did a bit of poking around... seems like most of the "out-of-the-box" solutions are paid.

We may have to come up with "iconography" and have people put it together in something like PPT?

[abrennan89]

There have been Slack threads with a ton of recommendations but we never decided anything:

• https://knative.slack.com/archives/CU9DGL4FM/p1597335889312100?thread_ts=1597334972.311500&cid=CU9DGL4FM
• https://knative.slack.com/archives/C9CV04DNJ/p1596113265354800
• https://knative.slack.com/archives/CU9DGL4FM/p1595874456259400

(Some of the discussions on the threads are unrelated but I've done my best to send links to the bits about standardizing tools)

@evankanderson @aslom @devguyio @rhuss @lionelvillard @aliok may have some thoughts / suggestions

[aliok]

I think I am pinged because I did some experiments with C4model :)

I tried the C4 model to draw diagrams for some projects: https://c4model.com/
It starts with the high level system landscape and goes into more detail in each step.
Tooling is good. The unpaid solution which can be containerized is to use https://github.com/structurizr/cli and let it generate a PlantUML file, which can be converted into a bitmap. The CLI is fed with code written against a DSL thus this approach enables diagrams-as-code.

However, it is not a general purpose tool. C4model is for drawing architecture diagrams. You cannot draw things like flow diagrams, etc.

[aliok]

I did a bit of poking around... seems like most of the "out-of-the-box" solutions are paid.

@omerbensaadon what were those solutions?

[rhuss]

I'm still a fan of good old plant uml as this allows for using markup for creating the diagrams, but I'm not sure if this is flexible enough as you can't do arbitrary graphs (which might be also a good thing). However, I would understand if people would prefer a more interactive tool.

Plant UML can do all sort of UML diagrams, including sequence diagrams, flow charts, component diagrams etc.

[evankanderson]

I've used UML for diagrams before, and it works well as long as you aren't too picky about layout.

A free tool for "pretty diagrams" might be Inkscape (Illustrator OSS competitor), but I suspect it has a steep learning curve. I've mostly used it to create pre-stream images via https://github.com/vmware-tanzu/think/master/documentation

[rhuss]

... images via https://github.com/vmware-tanzu/think/master/documentation

guess this is a private repo ? (404)

[markusthoemmes]

Just to add datapoints: https://github.com/knative/serving/blob/main/docs/scaling/SYSTEM.md was drawn using draw.io, and that worked just nicely.

[abrennan89]

Just to throw in my 2c, I'm also a big fan of Inkscape because I like vector graphics, but for standard diagrams Evan is right in that the learning curve is steep and it's also more time consuming to use for standard diagram stuff IMO.

Google Drawings is also a thing we could maybe look at? Keep it simple?

[aliok]

Google Drawings is also a thing we could maybe look at? Keep it simple?

When I am preparing blogposts and stuff I use Google Drawings and already a month later I can't find the source Google Drawing for the diagram that I need to fix a spelling mistake 😄
I guess same thing can happen here in Knative docs with a bigger scale. This effort needs to be very good organized if you decide to go with Google Drawings.

Same argument is valid for Draw.io.

I'm also a big fan of Inkscape
+1.

Good think about Inkscape is that it can be used within automation. The diagram source in "Inkscape SVG" format (that's regular SVG with a lot of invisible Inkscape metadata) can be kept in the repos and the Inkscape tooling can be used to generate the PNG/JPG within CI.

Having said that, I never tried this tooling in a container.

[omerbensaadon]

Taking a look at Draw.io and it looks pretty nice?

You can create a set of iconography in XML and link anybody to it, which is pretty sweet.

Check out Kubernetes here: https://app.diagrams.net/?splash=0&clibs=Uhttps%3A%2F%2Fjgraph.github.io%2Fdrawio-libs%2Flibs%2Fkubernetes.xml

It also looks like you can save things directly to Github or Google Drive which is nice?