At this year’s GUADEC, I made a proposal: that the GNOME project should migrate its documentation from wiki.gnome.org to other locations, and then disable its wiki. This blog post describes the proposal in more detail, in order to receive feedback from the wider community.
For many years, the GNOME wiki (a MoinMoin instance) has been the main source of internal project documentation. It contains key project information, including guidance for newcomers, the release schedule, pages for the various teams, and much more.
Today, much of the content on the wiki is out of date, and a large portion of it isn’t actively updated. Many activities have moved from the wiki to other platforms (particularly Gitlab), leaving the related wiki content to rot. There have also been problems with spam, which have meant that edit rights have to be manually granted.
This situation inevitably causes issues, particularly for new contributors who are trying to learn how to get involved.
The proposal is for us to replace the wiki with a combination of alternative platforms. The main alternatives would be:
- gnome.org, for small amounts of important high-level information
- developer.gnome.org, for technical documentation
- apps.gnome.org, for application home pages
- In-tree documentation, for individual project docs
- Gitlab issues in special-purpose projects, for more transient documentation
- A new project handbook site, for general project documentation (contribution guide, code of conduct, governance, release process, and so on)
We started using Sphinx for docs in GNOME after evaluating a variety of alternative solutions. It’s not the newest or trendiest docs tool, but it has some key features which made it a good choice for us:
- It’s a drop in tool which is both mature and well-maintained
- It generates static HTML, which makes deployment and hosting easy with CI and Gitlab pages
- Docs content is written using a light weight markup language
- We can easily restyle the docs sites to match GNOME branding
Our experience so far has been positive: Sphnix-based sites are easy to set up, deploy, host and edit.
Sphinx’s primary markup language is restructured text, which leads to the obvious question: can’t we use Markdown? Markdown is supported, so we could decide to use that. However, with the HIG, we found that restructured text gave a better experience overall ¹, and was light weight enough to not be burdensome ².
In terms of editing experience, you can make quick changes using Gitlab’s web-based editing tools or, for a richer experience, VS Code will give you live previews and error checking.
My suggestion for retiring the wiki would be to have a managed transition, which would look something like this:
- Create a migration guide for how and where to move existing wiki content
- Announce the transition period (including an end date)
- Transition! I’d finish the handbook, and other teams and individuals would be responsible for migrating their own content
- Finish the transition: archive the wiki, and update any links to point to the new docs locations
Archiving the wiki could take various forms depending on what is most practical. We could put it in read-only mode and add a banner, like we did with Bugzilla, or we could create a static archive and take it offline completely. I’ll leave that question to our sysadmins.
Pros and cons
I’m definitely not suggesting that this proposal is perfect. Nor am I suggesting that there aren’t other alternatives to consider (it would be great to hear any other ideas)! So, in the interests of transparency, here are the main pros and cons of the proposal.
Advantages of the new handbook site:
- It’s a nice website with good styling, clear navigation, and search
- Having a clear scope and purpose as the “GNOME Project Handbook” is very helpful for both documentation users and authors
- Having the content be maintained would (hopefully) result in higher overall quality
- The site would use a contribution workflow that is consistent with other GNOME Gitlab projects
And the disadvantages of the general proposal:
- There is more overhead required to make changes to docs stored in Git, compared to a wiki
- Making changes via Git requires more technical knowledge (though we can potentially minimize this with the Gitlab web IDE and good documentation)
- The new handbook site would run into problems if it were to become unmaintained
- Docs that aren’t hosted on the handbook site could be fragmented and hard to find
This proposal is just that: a proposal. We can and should consider alternatives. It also needs to be elaborated to cover all the requirements GNOME has today. If you have any concerns, suggestions, or uncertainties, please let me know.
¹ With restructured text, you get more powerful linking features, as well as internal link validation.