Hi Josh,

Josh Saddler <nightmorph <at> gentoo.org> 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 gentoo-wiki.com). 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