? It’s great tool for generating mobile friendly docs from markdown. And super awesome is the search. (no longer manual browsing of the docs, when you even don’t know where you should search). We at work are using it for documentation all the time - stored at Gitlab, after modifying documents, pipeline will regenerate the site and the wiki itself is then shown at Gitlab pages - it’s very customizable (themes, plug-ins ) and you can even load your own data using python hooks (runs e.g. in gitlab pipeline and spits out 100% static website, but allows to grab data from different places - eg. language translation status). There is also great extension Material for MKDocs that makes it prettier and more modern looking.
I’ve noticed your documentation is in some kind of XML flavour and it looks complicated (in comparison to markdown). Wouldn’t lowering this barier invite more people into the documenation process?
I’ve noticed that https://developer.gimp.org/about/ is already using another (markdown based) solution Hugo framework - I personally don’t have any experience with this, but it also looks more sympathetic than current solutions on other mentioned sites.
That “soime kind of XML flavor” is Docbook and very common. Maybe changing stuff from this to that might “lower the barrier”, maybe not at all and create new problems when markdown does not support current Docbook features.
That’s not really true, in my experience. It may make it easier to do long term maintenance of Markdown than Docbook, depending on the Markdown feature set you commit to, but onboarding new contributors is dominated by other factors:
how easy it is to check out the sources
how easy it is to build the documentation
how easy it is to commit a change
In my personal experience, it’s easier to get documentation changes if:
your documentation contains a link to the source at the right location in the repository web UI
it’s possible to edit the documentation directly from the web UI
the documentation gets built through the CI pipeline, and you can browse the output from the web UI
The format helps up to a point.
By way of an example: GNOME projects use an XML dialect (simpler that DocBook) for user documentation, a Markdown dialect for API references, and reStructureText for the developer documentation; no format has demonstrated a clear advantage in terms of inviting new contributors—unlike introducing a clear work flow that made it simpler to access the sources, modify them, and submit changes upstream, which definitely increased the number of contributions.
Periodic reminder that Markdown is a terrible format for anything that isn’t a very simple text, and that any and all improvements are custom extensions to the base grammar, which introduce a dependency on the implementation of those extensions.
The API reference for GNOME platform libraries is written using Markdown as defined by the Python-Markdown module, plus some custom extensions on top of it, and in the (unlikely) case the Python-Markdown module ever decided to break those extensions or its own format, we’d have to vendor the Markdown implementation in the API reference generator, and thus maintain a fork.
There’s definitely an advantage in relying on an expressive format that has been standardised elsewhere, like DocBook; of course, DocBook is also a pretty terrible documentation format straight out of SGML and the late '80s.
your documentation contains a link to the source at the right location in the repository web UI
in MKDocs, that’s possible - our docs pages (at my work) have Edit this page link that leads to the markdown file in repo.
it’s possible to edit the documentation directly from the web UI
No problem with markdown, it’s even rendered in some form in Gitlab (not necessarilly as final page, but good enough to see the structure of the document.)
the documentation gets built through the CI pipeline, and you can browse the output from the web UI
yop, no problem - you just run the tool on the folder with sources (from pipeline, from local machine, it doesn’t matter)
Only the manual uses Docbook XML, the developer website uses markdown as you noticed, and the gui website is a wiki that is probably going to be deprecated. Hugo is what we use for most of our website except the manual, and seems to work reasonably well. So there would need to be a strong reason to change that.
As for the manual, yes Docbook can be complicated and sometimes causes issues, but it also allows a lot of configurability. Probably a lot more than we need and I personally wouldn’t mind if someone investigated the advantages and disadvantages of using the same XML scheme as used by GNOME for their user documentation as mentioned above.
Since what we have now works for us, any change would need to show clear advantages in maintainability and user-friendliness to make the effort to change.
I am not convinced that changing to Markdown would generate substantially more contributors (which we would certainly welcome) than we have now.
Thanks for valuable input. I’ve meant documentation rather in general - therefore I’ve mentioned all of these - user docs, wikis,…
Ad Hugo - well, it’s just tool (alternative what I’ve mentioned with similar capabilities) and if it works for you, that’s great. What’s important is the ease of use - that’s markdown for authors and gitlab pipeline that produces reasonably good looking output that could be easily explored (which I’m little bit missing right now - check search here on MKDocs - nice live client side search via js).
As for DocBook, I’m not familiar with it so in the first glance, it looks like overkill for me. But if it suits your needs and works well, then ok…
I personally wouldn’t mind if someone investigated the advantages and disadvantages of using the same XML scheme as used by GNOME for their user documentation as mentioned above.
Can you be more specific about the XML scheme as used by GNOME - I thought that they are using DocBook and therefore Gimp is using it.
I wouldn’t sign that. Mallard’s linking between two docs pages is only one direction which makes maintaining custom distribution downstream patches much easier (only one file to add instead of also editing existing ones). For example.
Mallard’s linking between two docs pages is only one direction which makes maintaining custom distribution downstream patches much easier (only one file to add instead of also editing existing ones). For example.