I see some things that have been improved a lot, but also I see some new issues. Improvements are for example:
wayyyy better and prettier landing pages for people from outside the project
the overall quality of the content was increased a lot, and is much more up to date (I would say)
in general moving away from old software, to one with much better UX is good (gitlab, hedgedoc, discourse)
less maintainance (for example automation of apps.gnome.org)
But also I see some issues:
discoverability of new subpages, gitlab repos(wikis), hedgedocs
navigation between them is not as straight-forward
higher barrier to contribute (gitlab)
hedgedocs seem to get lost after they are not used anymore (of course this can be also a good thing, but at least some sort of archive would be useful)
As a conclusion I found myself thinking: Maybe a wiki is actually better for a few things? Of course with aspects like:
modern wiki software
small, defined scope (compared to previous wiki)
I see other projects (also that are smaller than gnome) using wikis quite successfully, so I was thinking, is it realistic for gnome to have one again as well?
Also as a contributor to the Vala Project, I can say that if there would be a good wiki platform, we definitely would move over the docs from a current gitlab/github based solution. Though I think most individual modules wouldn’t need that, only for larger ones with a lot of docs pages it makes sense.
Notably, the quantity of stale content has drastically decreased.
I do make some use of GitLab’s project-specific wiki feature, but it’s a little hidden and also vulnerable to stale content. For some cultural reason, people jump to fix stale content in git repos like handbook.gnome.org, whereas stale content on a wiki just languishes…
GNOME has wikis in GitLab now. So the “again” does not make sense?
The wikis in gitlab have issues though. They are not very discoverable, not centralised, don’t have that many features and aren’t as convenient to edit.
Of course the old wiki was worse in many aspects, but a new proper wiki could be much better.
Is there a way we can get the changes submitted and reviewed in GitLab, but publish the final content to a centralized site (/wiki) which is read-only?
The “convenience of wiki” is what is being exploited by spammers. We definitely don’t want to go back to traditional wiki, fighting spams and wasting our limited resources, unless there are new solutions (similar to Anubis handling bots) with advanced spam protection etc.
My perspective is that the handbook has generally been successful. Positives I could list include:
No more huge collection of obsolete content
We finally have guides for all the basic contribution steps. These were missing previously, due to the fact that the wiki never had an overarching structure or purpose.
Much higher information quality overall. Example: with the handbook, we finally have a good issue reporting guide.
Tooling to help maintain quality: built in spell checking, validation of formatting and internal links
Improved structure for the information we provide
Changes get reviewed and discussed now, which has been very significant in improving both quality and having a process to create guidelines and policies. Pages like we have now for signing releases wouldn’t have existed with the wiki.
Community members who are already familiar with the Gitlab workflow seem to have found it reasonably easy to make changes, as evidenced by the range of people making commits
According to the web stats, the handbook is being used
I do think that it would be good to have user data on the handbook though - it would be great to hear what people think of the experience of using it. It’s never going to be all positive, and there’s always room for improvement.
The main negatives I can see are:
The GitLab wikis aren’t very obvious and often seem to get ignored
The events pages don’t seem to get much attention, especially the hackfests. That part of the handbook might need to be rethought.
I don’t think that hosting a new standalone wiki is the right answer to these issues. It would be confusing which information should go where, and we’d end up with the same problems we had with the previous wiki, with unmaintained and poorly organised content.
The main problem with for example the handbook, is the barrier to contribute. Yes, maybe the gitlab workflow might be familiar to existing contributors already, but it still is so much more inconvenient than it would need to be.
I think it is especially important to make it easy for new people to contribute. If I want to add something to the handbook, I need to
have a gnome gitlab account
fork the handbook repo
do a change in the online editor (which is really not the best editor, also considering needing to know the right docs format)
open a merge request.
I haven’t counted how many clicks and waiting for new pages to load that is.
I think this is a huge cost, and its also the reason why I haven’t contributed anything to it yet. I don’t have that much time so it ends up not being worth the effort.
I see documentation also as a place where newcomers can do easy contributions to the project, so low barriers would help a lot.
Of course it depends on what kind of content there is. For example the release process is only something people experienced in releasing can contribute to, and discussions are important there. But I don’t think that is the average case. (discussions are of course always needed, to some extent, but afaik wiki software supports all that)
For events/hackfests, pads are used to organize them. They basically have all the advantages of a wiki, that it is easily editable etc, but they don’t get archived anywhere. People don’t make the effort with a MR etc, just to add a link somewhere.
I think that is one of the advantages of a wiki. That content stays on there. And also that it is discoverable. You can have a central index that lists all previous event pages.
It would be confusing which information should go where
I think if there would be a clear guideline on what goes where, it would be enough. The old wiki didn’t have anything like that afaik. Also if there are guidelines, a good structure of pages, maintenance wouldn’t be a big problem anymore.
There’s no denying that using a Sphinx site for project docs makes it harder for a single contributor to make a change. However, it also has huge advantages which I listed above and, for that reason, I think that the tradeoff is worth it.
You’d need to have a maintainer team for the wiki to be in charge of those guidelines, and you’d need regular review and cleanup to make sure that the content is high quality and follows the guidelines. In my experience that doesn’t generally happen in practice with wikis.
I get the points you’re making about ease of contribution and the limitations of Hedgedoc. Those are valid points. I just don’t think that a standalone wiki would leave us in a better place compared to what we currently have.
I would say many of the advantages the new websites have are valid, but a wiki wouldn’t be any worse. For example there is also good tooling, for reviewing and discussing, usabilty for viewers not less good, might have even more features.
You’d need to have a maintainer team for the wiki to be in charge of those guidelines
The same is also necessary for the websites.
Just because the old wiki was managed not very well, wasn’t structured, got reviews or had editing guidelines, doesn’t mean a new one would be like that too.
I think it would be worth to try out for selected areas. For example I would move the Vala documentation to the wiki. And then the details of how the reviewing process works etc, could be figured out.
I don’t think so? Did we have any spammers that managed to get into the TrustedEditorGroup? Doubt it? I think that really completely stopped all spam?
Mmm, Vala documentation seems like a worst-case scenario for a wiki? The vala documentation on the old wiki was extremely outdated. I would strongly prefer to maintain important project documentation like that in a git repo.
Hey everyone. Just wanted to give some ideas, too.
The main issue I see with the decentralised approach is discoverability. I would have never known the GNOME Handbook existed, unless I stumbled upon the link in a random chat message or somewhere else. I think many contributors are not aware of the site, or not aware of it’s full scope anyway.
Now this is only about the Handbook, but there are much more websites now, each with their own links, content editors, design and perhaps even content licences. While I agree that homogenising everything would be great, I don’t see it happening due to the failures of the wiki, hence I would at-least propose these:
Having a stronger Websites team, which will help new projects figure out where to host their documentation, help maintain current sites, and more.
Establishing clear rules on sites: how do I decide to host a static site, create a Gitlab wiki, or something else
Create a GNOME-wide index of ALL GNOME-related websites, including more official ones like gnome.org, foundation.gnome.org, blogs.gnome.org, planet.gnome.org to project-specific Vala documentation, to project-specific sites like the Vala website & documentation, gjs.guide and more.
So it seems consensus is to not change where for example the handbook is hosted, which I can also understand since it would be again a lot of work to migrate.
So there is one last thing:
The events pages don’t seem to get much attention, especially the hackfests. That part of the handbook might need to be rethought.
pads are very good quickly starting and organizing, the problem is that adding a link somewhere is relatively much work compared to the value. So maybe some other kind of way, maybe on pads, could display the list of old pads?
Moving documentation to a wiki is a great example when not to use a wiki - a website completely disconnected from reality (code and code comments). Code can (semi-)automatically update docs but not when those docs are on some external wiki exposed to random unverified changes by random people, guided by a misled “everyone can edit” ideology.