retirement: feedback wanted

That’s also what I also had in mind for the private board docs. The public docs could go on any of the following:

  • the new GNOME handbook docs site
  • the foundation website
  • a new docs site just for board documentation

The other potentially problematic case which hasn’t been raised so far is team documentation, like for i18n, docs, engagement and design.

Group-level wikis in Gitlab would have been the perfect solution for this, but unfortunately they are an enterprise feature. The only alternatives I currently have are:

  • Team READMEs, like the design team has
  • A project within a team’s Gitlab space that is used for docs (either through its wiki or in-tree docs in the repo)
  • Individual team docs sites (probably using Sphinx, like we do for developer docs and the HIG)

However, none of these are ideal. Team READMEs are hidden at the bottom of the page, and are just a single page. Dedicated docs projects in Gitlab are awkward from a navigation and discoverability perspective. Docs sites are OK if you have a lot of docs to maintain, but there’s obviously additional work involved in creating and maintaining them.

1 Like

I’ve worked up a draft of the wiki migration guide. Feedback would be welcome!


I’ve also been working on a first draft of the handbook site. The latest version can be seen at Home - GNOME Project Handbook documentation , and the project is Allan Day / GNOME Project Handbook · GitLab .

I think that the handbook will be more or less ready to move on to the wiki transition proper, once it’s moved to a team space in Gitlab.


My thoughts for this migration are:

On wikipedia (or other wikis), changes are reviewed after they are made, and contributors are told to “be bold”.

This introduced the spam and edit-war problem on the instance.

For important pages and information, it’s a good thing that changes are intended to be reviewed first before being applied. But it can be an hindrance for fixing trivial things such as a broken link or typos.

In any case, the parts of that are replaced by another mini-wiki (wiki located in a GitLab project) won’t suffer from the spam problem because it’s hosted on GitLab. But changes are still reviewed after-the-fact there (the workflow won’t change).

Another thought that I have is that it’s going to be a lot of migration work. For some teams that already lack man power, this can be seen as something not desirable. So like the bugzilla to GitLab issues tickets migration, an automatic tool to convert the wiki pages to something else would solve that problem.

Another thing, in all cases the MoinMoin syntax is less friendly than Markdown or reStructuredText, as already said.

So migrating things is well worth it, even if it takes time.

For teams with a lot of pages to migrate (and which lack the man power), let’s not rush things. For example if a warning message about the wiki being deprecated is added to all pages of the wiki, this would not be a pleasant experience. My suggestion is to add the warning message when editing a page, not in the page content itself.

My 2 cents :wink:


Maybe a tool like pretalx would be a nice fit for organizing events?

I mean we have an indicio for that - and while that’s a tad weird, it serves the job I think.

In lieu of that, has anyone a recommendation for a hugo theme (or any other static content generator, for that matter) that does not look too bad but also does not bring in half a ton of dependencies?

The design team has produced some simple static sites that might be of interest: Websites · GitLab. Or it’s easy to create your own Sphinx project if you want something for docs.


This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.