Use "drawio.png" editable PNGs as recommended diagram format

[mkschreder]

Is your enhancement proposal related to a problem? Please describe. When it comes to diagrams in sphinx documentation, it is often convenient to be able to edit them without having to convert between file types. It would be a good enhancement I think to standardize the format around the editable PNG with drawio information attached in the file.

Describe the solution you'd like That a new convention is introduced to use drawio editable png as the main diagram format that will replace svgs and any other formats currently used in Zephyr documentation to represent more complex diagrams.

Describe alternatives you've considered A lot of alternatives exist but editable pngs are the most convenient of all. these images look like pngs to any existing tools but also contain raw diagram data that can be edited with drawio and then saved. They work in merge requests and they are easier to work with than for example svgs. Editable pngs are extremely versatile.

Additional context I think the main reason they are not used more is because people are not aware that the format exists.

One huge drawback about not having this standardized is that we get massive amounts of PNGs and other formats that are impossible to maintain because they don't come with source document of the diagrams. Like for example the diagrams in the bluetooth folder which all seem to be conventional pngs: https://github.com/zephyrproject-rtos/zephyr/tree/main/doc/connectivity/bluetooth/img (Correct me if I'm wrong, but I was neither able to find a source document for many of these images, nor edit them in drawio).

[kartben]

Thanks for the suggestion and taking the time to file an issue!

This would be an interesting thing to consider indeed, probably part of more comprehensive guidelines regarding what makes a diagram "complex", as I think Graphviz and SVG should be preferred, the former for they really allow for a "diagram as code" approach, and the latter for they leave more flexibility regarding styling and keep file size under control. Also, as far as I remember draw.io also supports editable SVG (i.e. keeps the original diagram in the file's metadata), which IMO should be preferred.

FWIW I would like to also investigate a solution such as Mermaid.js in order to expand the scope of the types of diagrams that could be managed in "source form".

[thedjnK]

as I think Graphviz and SVG should be preferred

+1 on graphviz being preferred over drawio

[mkschreder]

I also generally prefer "everything as code" approach, but I also think that it has some major limitations when it comes to diagrams.

• Learning curve for non-engineers: many concept diagrams start in the hands of non-programmers and then make their way into code as programmers implement the details. This means that at best the diagram needs to be recoded in text if graphviz is used. This is wasteful. It is better to simply require the stakeholders to do the diagrams in drawio but save as editable images and then to continue maintenance in the repository.
• Intricacies in diagrams are hard to depict with text: as long as we only use standard template diagrams then we can usually use text but the moment we want to make something custom, drawio really stands out because it is very easy to create infographics in it.
• Diagrams as code require post processing: this means that in order to review the diagram, one often has to build the artifact or look in the final artifacts to see the result. This can be mitigated to a degree with editors where you can edit the code, but one still can not simply look at the diff in the merge request to see the diagram as a whole.

I think editable svg would work too just as long as it works in merge requests, changelog etc without any additional post processing.

[mkschreder]

One huge drawback about not having this standardized is that we get massive amounts of PNGs and other formats that are impossible to maintain because they don't come with source document of the diagrams. Like for example the diagrams in the bluetooth folder which all seem to be conventional pngs: https://github.com/zephyrproject-rtos/zephyr/tree/main/doc/connectivity/bluetooth/img (Correct me if I'm wrong, but I was neither able to find a source document for many of these images, nor edit them in drawio).

[cvinayak]

One huge drawback about not having this standardized is that we get massive amounts of PNGs and other formats that are impossible to maintain because they don't come with source document of the diagrams. Like for example the diagrams in the bluetooth folder which all seem to be conventional pngs: https://github.com/zephyrproject-rtos/zephyr/tree/main/doc/connectivity/bluetooth/img (Correct me if I'm wrong, but I was neither able to find a source document for many of these images, nor edit them in drawio).

The context of the PNGs in the Bluetooth Controller documentation can be found here: https://github.com/zephyrproject-rtos/zephyr/pull/50842

Member companies will be able to share the original power point presentation, i assume by a formal request. Some of the documentations pre-date contribution to Zephyr Project.

But generally, these diagram need rework anyway as they tend to have become a bit stale over the years.