Re: [gentoo-doc] Wiki for official docs only

[Josh Saddler]

AllenJB wrote:
> The existing docs team may know GuideXML well, but it seems to me that
> the existing docs team isn't sufficient and needs some new blood that it
> currently isn't getting. 2008.0 has been deprecated for months,
> autobuilds have been out for months, eselect profile is now available
> for profile selection and yet the handbooks haven't been updated at all
> (they even still mention the GRP, which iirc was never released for 2008.0!)

I dunno if new blood is needed . . . we have perfectly capable folks in
the docs team. They've been around for a few (or more) years, and
they've invested the time and trouble to write perfect GuideXML. The
problem is getting them up *off* their asses to do the work.

> 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.

> Following the documented instructions, you have to check out a large cvs
> tree, which takes some time and disk space, set up gorg (which in my
> opinion isn't very well documented) and possibly a web server (I think
> gorg may be able to run standalone, but I don't know how well it works
> and I could be wrong). Then you have to learn GuideXML. Then you have to
> learn how the handbook files are structured. Only then might a newbie to
> Gentoo documentation editing be able to actually start editing some docs.

On an unoptimized ReiserFS v3 layout, ~/cvs/gentoo/xml takes up 281MB.
More than 82MB of that is images.

I've never needed to compile and install gorg. In fact, I've refused to,
since I don't want to install a webserver just to work with docs, and I
don't want the bloat of Ruby for the same reason. I just use gvim and
nano. To each their own.

Also, we *do* have good documents for writing GuideXML, and we even tell
users how to look at the code for our existing docs to get a feel for
them. Heck, just the other day, someone I've never run into before
turned in an almost flawless new document to bugzilla.
http://bugs.gentoo.org/show_bug.cgi?id=275816

None of us helped him with his GuideXML as far as I know. This one came
out of the blue -- and it's a pretty damned fantastic doc. Users *are*
more capable than either of us typically give them credit. :)

> As stated before, I believe many are already familiar with mediawiki
> syntax due to its already extensive use in open source documentation and
> it's extremely well documented and easy to learn, with lots of support
> already available.

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.

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.

> I realize that there's work for infra involved in installing and
> maintaining a wiki. I realized that there's possibly work for some of
> the docs team in learning a new system and in initially porting
> documentation over (but some of this porting work may be offset by
> people like me who already know mediawiki well who would be willing to
> lend a hand in this task). However, I believe that in the long term, the
> benefits will easily outweigh these issues.

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.