[gentoo-project] [RFC] Reducing use of SMW in favor of something sane

[Michał Górny]

Hi,

TL;DR: MediaWiki sucks, SMW even more; let's start moving important
stuff out of it and into something sane. What replacements do you
suggest?


There was a long period during which we've attempted to move a lot of
Gentoo out of fancy XML files and into Wiki. This happened for project
docs, this happened for entire project structure and more more stuff.
On the other hand devmanual is still using fancy XML files in its own
git repository, and the main g.o site is using Jekyll.

Now that the main SMW proponent is MIA, I think it's time we look back
and think whether what has happened over time was good. I think it
wasn't, and I have a number of arguments to support that:

1. SMW lacks proper review platform, and the workflow is not suitable
for project docs.

2. It has a pretty high entry barrier, and is poorly documented.

3. Preview is half-working, and insufficient for more complex work.

4. It lacks proper offline editing capabilities.

5. The watching (mail notifications) are awfully cumbersome.

6. It is slow.

Now I'm going to expand on those points.


1: SMW lacks proper review platform, and the workflow sucks
===========================================================

MediaWiki is strongly bound to a specific workflow: users edit articles
as they see fit, and if they write something bad, someone else reverts
or fixes it. Such a workflow can work well for generic purpose articles
on sites with millions of users such as Wikipedia. However, it isn't
very fit for project documentation or policies where we really expect
every change to be made or at least approved by developers. As a result,
we restrict editing project pages to developers only.

Sadly, with no review platform this makes submitting updates for users
a PITA. All they can do is use project talk (which is usually ignored)
or submit bugs.

This is also a problem for developers -- when I want to work on doc
update that's supposed to be reviewed by others before being applied,
I end up having to copy text over to another page, work there, send it
for reviews (along with copy of the contents to facilitate context
replies) and afterwards merge it back to the original page. Unless I
want to spend a lot of time redoing all the changes separately,
the history ends up being split between the main doc and my working
copy. This also makes editing GLEPs a PITA.


2: It has a pretty high entry barrier, and is poorly documented
===============================================================

MediaWiki might have been cool when there was no alternative. Right now,
I dare say the only markup worse than MW is Textile. We have many decent
alternatives that are more predictable and easier to type -- RST,
Markdown, asciidoc. Users usually meet them anyway for various purposes,
so there's really no point in requiring them to remember MW.

What's even worse is that the basic markup is half-baked anyway. You
can't even make a proper table without having HTML attributes mixed in,
and you frequently end up using inline HTML (sometimes because you just
can't find a way to make MW syntax work).

Everything ends up being a horrible soup, in which you can't even
predict whether X will work without actually testing it. Sometimes you
need to escape stuff (also in unpredictable contexts), and there's not
even a single way to do that for all cases.

And that's just the basic use. If you start doing templates, things go
more complex. If you want to do the fancy SMW stuff, you're entering
the territory of true guesswork. The documentation is of moderate
quality, and is more focused on solving specific problems (i.e. how to
do X with Y) than on fully documenting how things work.


3: Preview is half-working, and insufficient for more complex work
==================================================================

All the above considered, preview becomes a very important feature.
Sadly, it's also mediocre. For a start, it renders some things
differently than the actual page (dunno if maffblaster already looked
at the problem). It's not nice when you spend a lot of time figuring out
why definition lists don't work, just to figure out it's a bug in page
preview.

Then, you can only preview the page you're editing. If you're working
on templates, SMW data and other hard magic, you're on your own.
Basically, you save the updates, wait a few seconds for other pages to
randomly refresh and see if your change hasn't broken them. Then you end
using 'trial and error' until things start working. All that on
the production instance where it could bite people using the wiki.

Not to mention the ability to test or at least reasonably predict that
some fancy SMW changes you won't break the existing data.


4: It lacks proper offline editing capabilities
===============================================

I might be wrong here but I'm not aware of any fully working, SMW-
friendly tools to work on articles offline. There's some git magic to
pull from MediaWiki but my short testing has shown it doesn't work very
well and can't handle the lot of our namespaces.

If you want on docs, you usually need to have your browser open
and a reasonably stable connection. Any offline work usually requires
extra effort, and a lot of handiwork.


5: The watching (mail notifications) are awfully cumbersome
===========================================================

So you can watch articles on MW and get mail notifications when someone
edits them. Cool. But someone thought it would be even cooler if you got
only one notifications per page until you revisited. And there's no
switch to turn this horrible misfeature off!

I get notification that someone did a trivial change on my page.
The description tells me what it was, and I know I don't have to visit
the article to check it. But I need to visit it anyway because otherwise
I wouldn't get notifications for more important changes! In fact, I need
to look at history immediately because this trivial change could already
have been followed by something important that I wasn't be notified of.

So if I read mail on phone, I need to mark mails to visit wiki articles
later (because someone decided to hide login controls on small screens!)
If I'm doing something else, I need to start browser and visit pages
hoping I won't run out-of-memory in the process.

It's real fun when notifications that are supposed to help you end up
enforcing a lot of effort just to keep them working.



6: It is slow
=============

I don't think this really needs much said. SMW is slow *even* for a PHP
software. Our resources could really be better utilized running
something that would benefit everyone rather than testing our patience.


What to move, and what to?
==========================

SMW is not something we can replace overnight. However, I think we
should slowly start moving important stuff out of it.

The project metadata is the first thing I'd like to have out of wiki
ASAP. Keeping it there is inconsistent, inconvenient and seems like
putting a lot of effort just to prove that SMW could be used for
anything.

We already keep developers in LDAP, and dump them onto main site. I see
no reason why we couldn't keep projects in LDAP or in a flat file
(api.gentoo.org), and include them on the main site rather than wiki. We
can still link to wiki entities for documentation, or maybe even figure
out how to include project members & so on from external source
on the wiki.

The next thing I'd like to move are project docs. We'd really use some
proper doc hosting for that, with a review platform and so on. Patrick
has suggested using flat files in a git repository -- and I think it
really makes much more sense than some fancy wiki software. If we need
more power, we could just use Jekyll as for the main site.

Fun fact is, even GitHub got that right. I think it might be even
possible to have GitHub pull requests with some degree of preview for
that. And if everything's in git, we can easily edit and preview it
locally.

I think it would be also reasonable to seek SMW replacement for regular
user docs. Even if we can't figure out something nice and git-backed,
any replacement would be much better. In fact, even Infra runs its own
wiki on DokuWiki which is much faster.


Your comments? Ideas?


-- 
Best regards,
Michał Górny