Unsurprisingly, I love Mallard. It captures a lot of what I consider best practices (and a few mistakes) from decades of doing docs and docs tools. It has features to solve problems that still no other format does to this day. It is far more pleasant to write than any other XML format. (I recognize that’s a low bar.)
I like Yelp. It does more under the hood than any other operating system’s help viewer. Its conditional processing is robust and powerful. Some years ago, I did some proof-of-concept work around doing the transforms in JS with Handlebar templates, because nobody else knows XSLT. It’s viable, but I don’t have the bandwidth to see it to completion alone.
None of this matters if nobody is writing docs.
I’m just one person, and my current job doesn’t revolve around docs. Either a group of people have to step into the work, or we have to scale what we do with what we can do. We can’t have our entire docs system be xkcd 2347.
I actually think a lot of app help could be served by something much, much simpler. Find or define a Markdown flavor with the features we will use and can maintain (yes to tables and notes/tips, no to embedded HTML). Render that in something like a GtkTextView. Do it in-process, no extra app. Don’t use web technologies, because that’s a never-ending source of CVEs, and it locks you out of EL distros. There are a lot of features we’d lose, but again, those don’t matter if nobody is writing docs.
As someone who offered help in writing documentation and as a (rather new) technical writer, I’d like to add my 2 cents as well. Sorry for the delayed reply.
I totally agree that it any effort is useless, unless some people are writing the documentation. To keep the entry barrier for new contributors low, I suggest using a Markdown based tool.
I’m currently migrating ReST (Readthedocs) documentation to a Markdown (GFM) based one (self hosted, based on Vitepress). We use gettext and Weblate for localization and the version management is completely done in Git. I would say it works pretty well. If you are interested, I can provide additional information. I saw many projects recently using Vitepress or similar tools.
For sure, I have no clue about all the places and required features for the Gnome documentation and I am not a dev who handles the technical infrastructure. Just wanted to bring this to the discussion, maybe it is helpful.
I would challenge the statement that nobody else uses Mallard because I did for giraffelibrary.org I chose it mainly because it could capture semantically-rich content without excessive complexity but there are other advantages for help documentation.
Although Mallard is not widely used, I think that is a weak reason in itself for moving away because it is well documented (well, it was when the website existed, and I’m sure that content can be reinstated somewhere). I had no trouble writing documentation with it, despite having never used it before. (Some things were hard to do given my limited understanding of XML technologies but I did manage, and these would have been difficult in any notation, if possible at all.) Whichever notation is used, potential authors may not have used it previously and will need to refer to documentation.
I find working with XML tedious for simple content, especially if it’s just paragraphs and lists, but for content that is not simple, I find markdown-like notations are more frustrating than using XML. Are there any open source structured content editors that could be used to create the XML?
I’m looking for a long-term opportunity to manage and build open source documentation and community, and this seems like a perfect opportunity for me. I want to put myself forward to take responsibility for keeping docs usable, current, and community-friendly.
I’ve spent years working on open source documentation projects. I’ve contributed to Wagtail and currently contribute to Canonical open-source projects, like the Ubuntu Packaging Guide documentation.
Have you considered migrating to a tool like Sphinx? In my experience, more open source communities are using Sphinx because it’s dynamic and well-suited to teams with many contributors. You can use reStructuredText or Markdown (via MyST) to handle complex documentation structures and page layouts.
Canonical is also building an open documentation academy. It’s designed to support open-source projects that want to expand their documentation and contributor base. I can help you connect with the team and facilitate that support.
For more information about my experience and background, please visit my website.
Sphinx is what the GNOME Handbook (Teams / Websites / handbook.gnome.org · GitLab) uses so it seems to me like a good strategic opportunity to use the same infrastructure for GNOME Yelp.
The main thing I’m not sure about using Sphinx is how to handle “decentralized” docs structure where other applications provided pages to GNOME Yelp as far as I can tell? I may be mistaken on that.
I chose it mainly because it could capture semantically-rich content without excessive complexity but there are other advantages for help documentation.