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
In Reply to: Re: [gentoo-doc] Wiki for official docs only by Josh Saddler
Hi Josh,

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