Updates from the release team

Community
,
1

On help

The release team just had their meeting for the 49 development cycle (two of them, actually), and discussed the current state of help and documentation in GNOME.
The executive summary is:

Help needs your help!

We are facing a number of overlapping issues here, and we would like to ask for help from the community. In no particular order:

  • Yelp is not actively maintained. Shaun is still around, but he does not have much time for yelp, and yelp is lagging behind in a number of transitions:

    • GTK4 port (yelp is the last thing dragging GTK3 webkit into our runtimes)
    • meson build system
    • CI (needed for doing releases, if nothing else)

  • We’ve recently had a CVE in yelp, and it was a bit of a struggle to get it fixed. This is unfortunately going to keep happening, since yelp relies on web technologies that can and will produce CVEs

  • The existing documentation is written in Mallard, which is a niche format that relies on its own tooling, and is also not actively maintained (the project Mallard website has disappeared, and some of the tooling does not build anymore with supported python releases)

  • The documentation team is basically dormant, so our help is not receiving the updates that it deserves

What is needed?

Shaun has thankfully agreed to try and help us get the most important MRs (meson, gtk4, ci) merged, but it would be very helpful to have more people contributing to yelp and helping to maintain it.

It would also be good to do a pass over the existing documentation and fix up the most outdated bits.

Longer-term, we need to think about replacing the documentation format and tooling. If you have experience in this area, your contribution could make a real difference.

This is a great reminder that it is not required to be a coder to make important contributions to GNOME. Everybody can help! If you don’t know where to start, come and ask us.

Thanks :heart:

13 Likes
2

Hi, I’m not a developer (I learn python and C at school but I didn’t use it for a few years) but I will like to start help open source project. I’m ready to learn new things if necessary (I love learning new stuff). Also I’m a native french speaker so I could do some translation work if needed.

3

Doesn’t Ubuntu/Canonical use Yelp helper too? Is there anyone on their team that might be able to lend any help as well if someone reached out to them perhaps?

4

Hi,
do you also mean that you’ll drop the WebKitGTK 4.1 API from the
Flatpak runtime once the yelp does not need it? The GNOME Evolution
(though not part of the GNOME core for some time now) uses it, and
surely will for quite some time, and it is available in the flathub.org
(262k installs as of today is not that many, that’s true) where it does
use the GNOME runtime. It’ll mean to build the WebKitGTK for each
update of it, if you’ll drop the WebkitGTK 4.1 API, right? How long
does it take to build it, do you know, please? A pointer to a build
recipe for the WebKitGTK 4.1 API in the Flatpak will help.

Thanks and bye,
Milan
5


On a 16 core Intel CPU i9-12900K (24) @ 5.20 GHz:

[8266/8273] Linking CXX executable bin/MiniBrowser
[8267/8273] Generating WebKit2-4.1.gir
[8268/8273] Generating WebKit2WebExtension-4.1.gir
[8269/8273] Generating WebKit2-4.1.typelib
[8270/8273] Generating WebKit2WebExtension-4.1.typelib
[8271/8273] Generating documentation: WebKit2
[8272/8273] Generating documentation: WebKit2WebExtension

==> Finished making: webkit2gtk-4.1 2.48.2-1 (Fri May 23 22:31:43 2025)

real	37m38.897s
user	0m0.085s
sys     0m0.191s


I’ve been building the past couple releases against GTK3 (built with -Dx11-backend=false) in order to run Evolution in an x11-less GTK environment, but this is the full standard build of WebkitGTK 4.1, version 2.48.2.

tl;dr…it’s a big build.

6

This is a great reminder that it is not required to be a coder to make important contributions to GNOME. Everybody can help! If you don’t know where to start, come and ask us

@matthiasc I’m willing to help wherever needed! How can I help reboot the documentation team?

7

Same here. I’m not a coder, but already creating/maintaining the documentation of an open-source project.

8

Developer here willing to help out.

9

Are you kidding? The Mallard format is really nice, and porting all our documentation to another format sounds like a great way to break it, break all the translations, and sink a huge amount of contributor time.

1 Like
11

Are you kidding? The Mallard format is really nice, and porting all our documentation to another format sounds like a great way to break it, break all the translations, and sink a huge amount of contributor time.

Mallard is not really widely adopted by technical writers. I agree we’d be better off with some more universal/popular tooling.

12

That’s a fair point to consider, but is our problem that we don’t have enough technical writers because they don’t like the format, or for some other reason?

My point is that changing documentation formats is a huge and disruptive task, and it would be a shame to decide to do that without a really good justification.

Anyway, I’ll stop distracting from the thread.

13

Mallard is also a locally sourced, organic, artisanal format that nobody else uses, which is a hard sell for any new documentation writer—something that has been pretty common over the past couple of years.

The Mallard format is unmaintained, the documentation of the format itself is unavailable; the tooling itself is, by and large, unmaintained and bitrotting; it’s slow and overcomplicated because it’s all built around XSLT.

Mallard’s only saving grace is its support for localisation—unfortunately, it is built around gettext, which is a terrible format barely suited for localising static strings in C programs, and the only reason why Mallard is using it is because we are, as a platform and a community, hostage to gettext and the POSIX localisation API. Even with that said, we have had multiple build failures because translators broke the markup; I suspect that the only reason why we’re not seeing those project-wide breakages any more is that we don’t have new documentation being written at all.

I’m also questioning whether you’re up to date with the current state of the documentation; considering that most of if it is still written around GNOME 3.x and has barely been updated to GNOME 40+, I don’t think there’s stuff left to “break”. Any attempt at updating the documentation is going to be indistinguishable from a rewrite.

1 Like
14

Honestly it might be better to just remove the documentation and not replace it. I suspect not many people use it.

1 Like
15

I agree with @ebassi and @felipeborges. It doesn’t really matter how nice mallard is as a format, if no one knows it and the tooling around it isn’t maintained, we cannot seriously consider to continue using it.

Honestly, some of us took a quick look at what we have right now, and some of it was useless, some of it was making excuses for brokenness, some were opinions of the authors.

I know this sounds harsh, but I recommend all of us to sample what we currently have and think about what parts of it are actually useful. If we don’t find a way to prevent the same from happening again, @mcatanzaro might be right and we should just remove it for now.

16

I also think the “global” documentation in gnome-user-docs is generally better than application-specific documentation.

1 Like
17

I’m glad we’re having this conversation! We should agree on a rough plan for docs - that would make it easier for people to contribute and/or attract resources.

Some points on what to do about docs both in the short and the long term:

Short term

I think we need to recognise that the existing online docs are causing problems, and have been causing problems for a long time.

We were collecting anonymous visitor stats on help.gnome.org for a while, and we saw that the help web pages get a lot of traffic. Some of the pages with the most traffic were:

Some of this material is extremely out of date. It’s misleading, and it makes GNOME look bad.

The other issue we have is old user help appearing in search results. For example, for a long time, the top Google search result for “report GNOME issue” has been this outdated Sudoku help page.

We should either clean up the online user docs, or take them all down.

Longer term

I think that it’s clear that we need to replace Mallard. I say this as someone who has written a fair amount of Mallard in the past. Writing XML by hand and with limited tooling is extremely hard work. Mallard was one of the reasons I stopped writing the release notes for a while. When we switched over to reST, my motivation and productivity shot up.

Sadly, it also seems that we probably need to steer clear of using web technologes for the help viewer.

So we need to rethink, and we probably need to break the problem down into its constituent elements: system onboarding, system docs, app docs, help with common problems, online help versus local, etc, etc.

One potential arrangement might be to port the existing system user help to a new website. It would primarily be an online resource, but we could consider shipping a local version. We could simultaneously create a new tips app written in GTK/Libadwaita (ie. no web technologies), which would be good to have in any case, and would mean that we’d at least have some kind of replacement for Yelp.

One thing that would help would be to have enhanced support for text layout in GTK/Libadwaita, so it’s possible to create nicely formatted pages of text without the aid of the web.

App docs is probably the most challenging aspect of all this. Personally I can see the case for having app docs, if they were focused on common problems/questions. I can also see the case for providing additional information on relatively complex or technical features. However, I think we have to recognise that many (if not most) of our apps are missing docs today, and that adding this documentation would be a significant undertaking that we are not in a position to undertake. Maybe app docs sadly need to go away, at least for now.

3 Likes
18

Has anyone spoken to a technical writer (either an existing or former member of the GNOME docs team, or someone else) about what they would find useful, and what they think is the problem with GNOME documentation/the docs team at the moment?

I assume someone has, but there’s no mention of it above (that I can see).

Are we talking about just https://gitlab.gnome.org/GNOME/gnome-user-docs/, or all use of Mallard across all our apps and repositories?

Is the amount of effort required to port all the still-relevant docs to a new format, and update them, and fix all the bugs with the port, more or less than the amount of effort required to fix Yelp and the bugs in the Mallard website/tooling (which I think are probably quite minor, because it’s a stable tool which has been in use for a long time).

Having written a reasonable amount of app and development documentation, and still dealing weekly with the fallout from our previous port from an unmaintained docs format (gtk-doc) to a new format (gi-docgen), you can perhaps understand why I might be pessimistic about the value of throwing everything in the bin and starting from scratch.

Looking forward to being called ignorant again.

19

I definitely agree that we should carefully consider the decision and talk to domain experts. My idea for how to handle the docs is fairly vague, and needs a lot more scrutiny and thought. It might well be a terrible. :slightly_smiling_face:

For what it’s worth, I do think of myself as a technical writer of sorts - I’ve written most of the release notes since 2011, I wrote the Flatpak docs, the HIG, the project handbook, and I’ve poked at RHEL documentation. I’ve done some cursory surveys of the docs tooling that’s currently available.

Every project and platform that I’ve seen in recent times uses some form of lightweight markup - either Markdown, reStructuredText, or AsciiDoc. I’ve never seen another project using XML for docs (well, not for a very long time). But then I’ve only ever encountered relatively simple technical content. I would be interested to know what gets used for more extensive user docs in the commercial world. (I’m assuming that it’s all bespoke and probably uses databases?)

In my really not properly thought out approach, core GNOME apps wouldn’t link to help, and Yelp and its dependencies would no longer be part of our releases.

I appreciate your comments, @pwithnall . Debate is good.

1 Like
20

Thanks Allan, that sounds like useful research to do.

Note that Mallard already has a lightweight markup variant called Ducktype. Some of the D-Bus docs are written in it. It’s another custom format, like the main Mallard format, but iirc it was explicitly designed to handle the use case of “technical writers don’t like XML”.

It’s less mature than the rest of Mallard, but I thought it should be mentioned as a partial response to the “nobody likes writing XML” point someone raised.

Anyway, I’m going to bow out of this because I need to spend any docs time I have on continuing to port from gtk-doc to gi-docgen.

21

André has written this blog post recently for the GIMP user manual which is written in DocBook (so an older XML format than Mallard):

https://blogs.gnome.org/aklapper/2025/04/24/gimp-user-docs/

I also know that the SUSE docs are written in DocBook. (BTW there are some downstream GNOME docs in there).

Also, one needs to remember that older versions of GNOME had its user docs written in DocBook as well (for GNOME 2 at least). GNOME has benefited at lot from the help of Sun Microsystems. Today it seems that there are less human resources for GNOME.

I didn’t contribute back then, when there was a switch from DocBook to Mallard for the user docs. I was one of the earliest adopter of Mallard when it was still fresh. I suppose that the switch was a lot of work though for you older GNOME contributors. Maybe we can learn by past events.

My 2 cents.