Gentoo Archives: gentoo-doc

From: Robert Buchholz <rbu@g.o>
To: gentoo-doc@l.g.o
Subject: [gentoo-doc] Re: Wiki for official docs only
Date: Sun, 19 Jul 2009 14:23:31
Message-Id: loom.20090719T142247-763@post.gmane.org
In Reply to: Re: [gentoo-doc] Wiki for official docs only by Josh Saddler
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