search

knative / ux

UX WG repository for assets and stories
10 stars 23 forks source link

Decide on a standard diagram tool for the Knative project #30

Open abrennan89 opened 3 years ago

abrennan89 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

(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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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

guess this is a private repo ? (404)

markusthoemmes commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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?

omerbensaadon commented 3 years ago

@aliok I am less concerned with automation unless you see an obvious use-case?

@abrennan89 I opened up InkScape and the learning curve looks steeper than draw.io?

omerbensaadon commented 3 years ago

@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?

Honestly, I don't remember now, none of them seemed suitable for us anyhow. One of them was OmniGraffle which is macOSX specific. Each of them had a "pricing" tab, the options we are discussing above seem better suited for our needs

omerbensaadon commented 3 years ago

Just commenting to say that mkdocs has this plugin for draw.io: https://github.com/LukeCarrier/mkdocs-drawio-exporter

Which I reckon strengthens the case for draw.io.

Check out other visual tool-related plugins here: https://github.com/mkdocs/mkdocs/wiki/MkDocs-Plugins#images-tables-charts--graphs

csantanapr commented 2 years ago

I have been using lately excalidraw for my knative presentations I use the excalidraw container as knative serving and then load the presentation drawing there

https://github.com/csantanapr/knative-kind/blob/master/knative.png https://github.com/csantanapr/knative-kind/blob/master/knative.excalidraw

Ref: https://github.com/excalidraw/excalidraw https://excalidraw.com/