Stream: docs

Topic: how others do

Oliver Bertuch (Mar 03 2026 at 12:37):

I'm going to listen in here: https://events.hifis.net/event/2945/contributions/21197/

Philip Durbin 🚀 (Mar 03 2026 at 13:46):

Will it be recorded?

Oliver Bertuch (Mar 03 2026 at 14:10):

I don't think so.

Philip Durbin 🚀 (Mar 03 2026 at 14:10):

bah, please take good notes :smile:

Oliver Bertuch (Mar 04 2026 at 10:31):

Here are the slides from the talk: https://doi.org/10.5281/zenodo.18848976

Oliver Bertuch (Mar 04 2026 at 10:31):

It was interesting to see how they do it.

Oliver Bertuch (Mar 04 2026 at 10:32):

In their multi-repo approach, they use Markdown to document the different bits and pieces. They combine all of them using Jekyll (switching to Hugo soon)

Oliver Bertuch (Mar 04 2026 at 10:32):

They are a part of GSoC this year and already have received a huge amount of contributions, not just for the docs transition.

Oliver Bertuch (Mar 04 2026 at 10:33):

To integrate documentation like XML schema docs etc (example) he said they use converters to MarkDown and then include these in the build of the docs page

Oliver Bertuch (Mar 04 2026 at 10:34):

They do follow Diataxis which we discussed a few times already.

Oliver Bertuch (Mar 04 2026 at 10:39):

In addition to the slides, https://quarto.org/ was mentioned as a way to write documentation.

Oliver Bertuch (Mar 04 2026 at 10:42):

It was interesting to see in the talk how they use Prince for PDF exports as well as Plausible to track usage of their docs. This may be quite interesting for our guides, too, learning which parts of the documentation are heavily used, how people interact with it etc.

Oliver Bertuch (Mar 04 2026 at 10:43):

(This was not part of the slides, only of the live talk :wink: )

Last updated: Apr 03 2026 at 06:08 UTC