Adding diagrams to docs

Package Maintainer Docs cover certain topics that would benefit from explanations by diagrams.
For example, the Package Review Process is quite complex.
I am sure that there are also other places where diagrams would be useful.

The questions: What is the best way to add diagrams,
and is the current tooling good enough?

One simplistic way is to just create them somehow and add as images.
But this is quite difficult to maintain.

Program Management Docs have a bit better approach,
they also include a source form in separate img_src folder.

For me, the preferred approach would be to use a textual source format that can be embedded in the page sources,
then have the site generator transform that into an image.
Asciidoctor Diagram extension seems to do exactly that.
Apparently, that is not available for Fedora Docs,
because I did not get the examples working.

Would it make sense to add that extension,
or something else with similar capability??

2 Likes

It would make sense to me, and asciidoc is capable of doing this. I know a picture would be worth a thousand words for some of the relationships involved in packaging review as you note, it would also be nice to not have to make some of those images and produce them inline with asciidoc code instead of having to curate the images as a sub dir of the doc’s. I’m thinking UML style images here, charts, flow diagrams, etc… Like for instance with Graphviz, which is a part of AsciiDoc as supplied by the Fedora repo’s.

1 Like

Good to hear that I am not alone thinking this would be a good feature.
I also noticed that this has been discussed before elsewhere:
Issue #104: [RFE]Support for creating diagrams from text (eg. Graphviz, diagrams.js, PlantUML, etc.) - docs-fp-o - Pagure.io

I also realized that the AsciiDoctor Diagram externsion I linked to is not useful,
because that is for Asciidoctor (a Ruby implementation of Asciidoc)
while Antora uses Asciidoctor.js (JavaScript as the name says).
However, there is another extension for that:
GitHub - Mogztter/asciidoctor-kroki: Asciidoctor.js extension to convert diagrams to images using Kroki!
I did some tests and got it working, too:
Tree - fedora-docs/package-maintainer-docs - Pagure.io
The remaining weakness I am aware of is that the extension delegates the actual conversion to kroki.io service.
If dependency to that is not desired,
a local Kroki instance must be available during the site build.
That should not be difficult,
since there is a container image available for that:
Using Docker or Podman :: Kroki Documentation

If there is agreement that this is a good feature to have,
and doing it with Kroki as outlined,
I can see if I can transform my test to a production quality pull request for the docs-fp-o repository.

3 Likes

Hmm,
I used asciidoc (the pkg) installed from the official Fedora repo, and it has Graphviz included. It would make sense that the doc’s site used js though.

1 Like

Generally speaking, we should be judicious with using images like diagrams. Although they can communicate much information (“a picture is worth a thousand words”, they say), they require more maintenance and are harder to localize.

That being said, there are definitely cases where the communication value of an image exceeds the maintenance burden. As of right now, I think a Dia (or other open tool) checked in to the repo with images exported for the docs is our best option. But if we can get Graphviz enabled, that would be much easier for flow diagrams and the like.

I’m all in favor of trying to get this to work on staging and then we can evaluate it. I don’t anticipate negative issues from this, unless it makes the translation workflow more difficult.

2 Likes