1 |
Hi, |
2 |
|
3 |
TL;DR: MediaWiki sucks, SMW even more; let's start moving important |
4 |
stuff out of it and into something sane. What replacements do you |
5 |
suggest? |
6 |
|
7 |
|
8 |
There was a long period during which we've attempted to move a lot of |
9 |
Gentoo out of fancy XML files and into Wiki. This happened for project |
10 |
docs, this happened for entire project structure and more more stuff. |
11 |
On the other hand devmanual is still using fancy XML files in its own |
12 |
git repository, and the main g.o site is using Jekyll. |
13 |
|
14 |
Now that the main SMW proponent is MIA, I think it's time we look back |
15 |
and think whether what has happened over time was good. I think it |
16 |
wasn't, and I have a number of arguments to support that: |
17 |
|
18 |
1. SMW lacks proper review platform, and the workflow is not suitable |
19 |
for project docs. |
20 |
|
21 |
2. It has a pretty high entry barrier, and is poorly documented. |
22 |
|
23 |
3. Preview is half-working, and insufficient for more complex work. |
24 |
|
25 |
4. It lacks proper offline editing capabilities. |
26 |
|
27 |
5. The watching (mail notifications) are awfully cumbersome. |
28 |
|
29 |
6. It is slow. |
30 |
|
31 |
Now I'm going to expand on those points. |
32 |
|
33 |
|
34 |
1: SMW lacks proper review platform, and the workflow sucks |
35 |
=========================================================== |
36 |
|
37 |
MediaWiki is strongly bound to a specific workflow: users edit articles |
38 |
as they see fit, and if they write something bad, someone else reverts |
39 |
or fixes it. Such a workflow can work well for generic purpose articles |
40 |
on sites with millions of users such as Wikipedia. However, it isn't |
41 |
very fit for project documentation or policies where we really expect |
42 |
every change to be made or at least approved by developers. As a result, |
43 |
we restrict editing project pages to developers only. |
44 |
|
45 |
Sadly, with no review platform this makes submitting updates for users |
46 |
a PITA. All they can do is use project talk (which is usually ignored) |
47 |
or submit bugs. |
48 |
|
49 |
This is also a problem for developers -- when I want to work on doc |
50 |
update that's supposed to be reviewed by others before being applied, |
51 |
I end up having to copy text over to another page, work there, send it |
52 |
for reviews (along with copy of the contents to facilitate context |
53 |
replies) and afterwards merge it back to the original page. Unless I |
54 |
want to spend a lot of time redoing all the changes separately, |
55 |
the history ends up being split between the main doc and my working |
56 |
copy. This also makes editing GLEPs a PITA. |
57 |
|
58 |
|
59 |
2: It has a pretty high entry barrier, and is poorly documented |
60 |
=============================================================== |
61 |
|
62 |
MediaWiki might have been cool when there was no alternative. Right now, |
63 |
I dare say the only markup worse than MW is Textile. We have many decent |
64 |
alternatives that are more predictable and easier to type -- RST, |
65 |
Markdown, asciidoc. Users usually meet them anyway for various purposes, |
66 |
so there's really no point in requiring them to remember MW. |
67 |
|
68 |
What's even worse is that the basic markup is half-baked anyway. You |
69 |
can't even make a proper table without having HTML attributes mixed in, |
70 |
and you frequently end up using inline HTML (sometimes because you just |
71 |
can't find a way to make MW syntax work). |
72 |
|
73 |
Everything ends up being a horrible soup, in which you can't even |
74 |
predict whether X will work without actually testing it. Sometimes you |
75 |
need to escape stuff (also in unpredictable contexts), and there's not |
76 |
even a single way to do that for all cases. |
77 |
|
78 |
And that's just the basic use. If you start doing templates, things go |
79 |
more complex. If you want to do the fancy SMW stuff, you're entering |
80 |
the territory of true guesswork. The documentation is of moderate |
81 |
quality, and is more focused on solving specific problems (i.e. how to |
82 |
do X with Y) than on fully documenting how things work. |
83 |
|
84 |
|
85 |
3: Preview is half-working, and insufficient for more complex work |
86 |
================================================================== |
87 |
|
88 |
All the above considered, preview becomes a very important feature. |
89 |
Sadly, it's also mediocre. For a start, it renders some things |
90 |
differently than the actual page (dunno if maffblaster already looked |
91 |
at the problem). It's not nice when you spend a lot of time figuring out |
92 |
why definition lists don't work, just to figure out it's a bug in page |
93 |
preview. |
94 |
|
95 |
Then, you can only preview the page you're editing. If you're working |
96 |
on templates, SMW data and other hard magic, you're on your own. |
97 |
Basically, you save the updates, wait a few seconds for other pages to |
98 |
randomly refresh and see if your change hasn't broken them. Then you end |
99 |
using 'trial and error' until things start working. All that on |
100 |
the production instance where it could bite people using the wiki. |
101 |
|
102 |
Not to mention the ability to test or at least reasonably predict that |
103 |
some fancy SMW changes you won't break the existing data. |
104 |
|
105 |
|
106 |
4: It lacks proper offline editing capabilities |
107 |
=============================================== |
108 |
|
109 |
I might be wrong here but I'm not aware of any fully working, SMW- |
110 |
friendly tools to work on articles offline. There's some git magic to |
111 |
pull from MediaWiki but my short testing has shown it doesn't work very |
112 |
well and can't handle the lot of our namespaces. |
113 |
|
114 |
If you want on docs, you usually need to have your browser open |
115 |
and a reasonably stable connection. Any offline work usually requires |
116 |
extra effort, and a lot of handiwork. |
117 |
|
118 |
|
119 |
5: The watching (mail notifications) are awfully cumbersome |
120 |
=========================================================== |
121 |
|
122 |
So you can watch articles on MW and get mail notifications when someone |
123 |
edits them. Cool. But someone thought it would be even cooler if you got |
124 |
only one notifications per page until you revisited. And there's no |
125 |
switch to turn this horrible misfeature off! |
126 |
|
127 |
I get notification that someone did a trivial change on my page. |
128 |
The description tells me what it was, and I know I don't have to visit |
129 |
the article to check it. But I need to visit it anyway because otherwise |
130 |
I wouldn't get notifications for more important changes! In fact, I need |
131 |
to look at history immediately because this trivial change could already |
132 |
have been followed by something important that I wasn't be notified of. |
133 |
|
134 |
So if I read mail on phone, I need to mark mails to visit wiki articles |
135 |
later (because someone decided to hide login controls on small screens!) |
136 |
If I'm doing something else, I need to start browser and visit pages |
137 |
hoping I won't run out-of-memory in the process. |
138 |
|
139 |
It's real fun when notifications that are supposed to help you end up |
140 |
enforcing a lot of effort just to keep them working. |
141 |
|
142 |
|
143 |
|
144 |
6: It is slow |
145 |
============= |
146 |
|
147 |
I don't think this really needs much said. SMW is slow *even* for a PHP |
148 |
software. Our resources could really be better utilized running |
149 |
something that would benefit everyone rather than testing our patience. |
150 |
|
151 |
|
152 |
What to move, and what to? |
153 |
========================== |
154 |
|
155 |
SMW is not something we can replace overnight. However, I think we |
156 |
should slowly start moving important stuff out of it. |
157 |
|
158 |
The project metadata is the first thing I'd like to have out of wiki |
159 |
ASAP. Keeping it there is inconsistent, inconvenient and seems like |
160 |
putting a lot of effort just to prove that SMW could be used for |
161 |
anything. |
162 |
|
163 |
We already keep developers in LDAP, and dump them onto main site. I see |
164 |
no reason why we couldn't keep projects in LDAP or in a flat file |
165 |
(api.gentoo.org), and include them on the main site rather than wiki. We |
166 |
can still link to wiki entities for documentation, or maybe even figure |
167 |
out how to include project members & so on from external source |
168 |
on the wiki. |
169 |
|
170 |
The next thing I'd like to move are project docs. We'd really use some |
171 |
proper doc hosting for that, with a review platform and so on. Patrick |
172 |
has suggested using flat files in a git repository -- and I think it |
173 |
really makes much more sense than some fancy wiki software. If we need |
174 |
more power, we could just use Jekyll as for the main site. |
175 |
|
176 |
Fun fact is, even GitHub got that right. I think it might be even |
177 |
possible to have GitHub pull requests with some degree of preview for |
178 |
that. And if everything's in git, we can easily edit and preview it |
179 |
locally. |
180 |
|
181 |
I think it would be also reasonable to seek SMW replacement for regular |
182 |
user docs. Even if we can't figure out something nice and git-backed, |
183 |
any replacement would be much better. In fact, even Infra runs its own |
184 |
wiki on DokuWiki which is much faster. |
185 |
|
186 |
|
187 |
Your comments? Ideas? |
188 |
|
189 |
|
190 |
-- |
191 |
Best regards, |
192 |
Michał Górny |