1 |
Hi Josh, |
2 |
|
3 |
Josh Saddler <nightmorph <at> gentoo.org> writes: |
4 |
> > How many of the existing docs team have never worked with mediawiki (or |
5 |
> > another wiki - I'm using mediawiki as an example because I suspect it's |
6 |
> > the most likely choice)? |
7 |
> |
8 |
> I sure don't know how the hell it works. I've half-heartedly poked at |
9 |
> Wikipedia and the old gentoo-wiki when trying to fix really egregious |
10 |
> errors, but it's still nigh-uncomprehensible. |
11 |
|
12 |
I for one find Wiki Syntax a lot easier to read since the text-only (source) |
13 |
version looks not much different from the rendered version. There are two main |
14 |
advantages to the existing docs: |
15 |
|
16 |
1) The preview feature is built-in |
17 |
|
18 |
I have written and edited some GuideXML documents. I have never done so without |
19 |
making a mistake. Getting the document rendered is a huge hassle (for me). I |
20 |
need to install a web server and some additions (which I need root for usually). |
21 |
Or I need to ssh to dev and see the doc there. Images and links will break. |
22 |
|
23 |
2) The change submission system is built in |
24 |
|
25 |
This is two sided: To commit something I do not need CVS, saving is built in. I |
26 |
do not need to prepare unreadable* patches. I do not need Bugzilla to make a |
27 |
change, and merging changes is a one-click operation for the wiki editors. |
28 |
MediaWiki has all these functions built in. Users can sign up, make a change |
29 |
from anywhere. And the docs team can use the "reviewed revision" feature to hide |
30 |
changes from others until they are reviewed. |
31 |
|
32 |
* because of realignment of word wraps, for instance |
33 |
|
34 |
|
35 |
> I don't know who these many others are, but I know the docs team doesn't |
36 |
> know the syntax. I, myself, find any and all wiki syntax completely |
37 |
> illegible and very difficult to parse. |
38 |
> |
39 |
> As the most (only?) active member of the GDP, I can tell you that I'd |
40 |
> probably quit if we switched to a wiki right now. |
41 |
|
42 |
Now I'm not telling you to change to a Wiki. I agree the docs team is doing a |
43 |
great job in keeping their pages up to date. However, I see advantages with |
44 |
fixing errors in old docs if people can just do updates themselves. |
45 |
|
46 |
There are also other benefits in having a wiki: Fedora is preparing their |
47 |
newsletter wiki-style and they just send it when it's done. I does not need the |
48 |
huge step of integrating articles sent in via email. |
49 |
|
50 |
You have to acknowledge the fact that there is a market for wikis in general, |
51 |
and for Gentoo in particular as well (see gentoo-wiki.com). I think it is |
52 |
something we could use to get fresh blood, and a higher flow into the docs. |
53 |
And that said, I completely acknowledge the fact that you run the team and it is |
54 |
ultimately your choice based on taste, experience and different consideration on |
55 |
argument. I just try to give my view here. |
56 |
|
57 |
|
58 |
> It's too much upheaval to try to switch everything over to a wiki. We'd |
59 |
> need all hands on deck for several months just to get our existing |
60 |
> content base over, and that doesn't take into account the continual |
61 |
> influx of new bugs, updates, and whatnot that would roll in during that |
62 |
> time. Trying to do all that with just one person . . . not gonna happen. |
63 |
|
64 |
Moving the docs is indeed not an easy task. I think the step of converting the |
65 |
existing docs is feasible to automate. What's not so easy is how we |
66 |
integrate/replace the existing page structure. Will XML project pages die? What |
67 |
about all the specific extensions (like auto-generated roll pages, glsa index, |
68 |
insertion of dev names, etc.). |
69 |
|
70 |
|
71 |
> Wikis are huge security risks, which is why historically infra has never |
72 |
> wanted to run a public wiki. In the previous (recent) three discussions |
73 |
> of the idea of an "official" sanctioned wiki, infra has told the GDP on |
74 |
> the MLs and on IRC that they are reluctant to run a public wiki because |
75 |
> of the security risks. |
76 |
|
77 |
Infra is doing a tremendous amount of work keeping our machines running. But |
78 |
eventually, their task is to enable Gentoo devs to do their work. If the |
79 |
community agrees they need a wiki, I am convinced they can make it happen. |
80 |
We are running a phpBB and Bugzilla instance as well. And MediaWiki has a very |
81 |
good track record of (1) no high-impact security issues and (2) fixing them fast |
82 |
and documenting them properly. |
83 |
|
84 |
|
85 |
|
86 |
Robert |