Suggestion for flowcharts/visuals/diagrams/images moving forward about docs HOT 5 CLOSED

Example PR, where I uploaded the .jpg and .xml.zip, then referenced the .jpg on a relevant docs page: #1313

from docs.

@danamlewis
I would only use it where the infographic has a clear benefit over normal text.
I don't think there is such a benefit in the example above.

Also always use .png, because .jpg will be less readable.
Larger images have the tendency to give problems with printing and on mobile devices.

Further downsides:

• words on images will not be found by search engines

So, please use with care, and avoid if possible.
And of course keeping the .xml close to the picture is a good idea.

from docs.

Thanks, @PieterGit. These are not intended to replace thorough documentation, or large portions of documentation at all, but add a supplementary image at the top of the page to summarize what's on the page at a high level. (This is for people who's eyes glaze over at a page of written text, which is a frequent comment we hear.) Take a look at the example PR, where the image is added as a supplement, and no written content is removed from the page.

from docs.

@danamlewis You mean
https://github.com/openaps/docs/blob/4bcbf369b6dea805cf564a86ef1b4c2c2590ffb7/docs/docs/Troubleshooting/Rig-NS-communications-troubleshooting.md

I don't think the specific (info)graphic (with bad practices like vertical text, lots of colors without function (color blind?), reduced contrast of white font color, jpg instead of png) will make things easier to read/summarize/glaze). I can imagine in a real flow chart like https://openaps.readthedocs.io/en/latest/docs/Gear%20Up/pump.html or infographic with far less text this kind of feature is useful.
See e.g. https://venngage.com/blog/infographic-design/

On the specific page I would expect the graphic to contain only a subset of the text which is already on the page.

from docs.

from docs.