Gentoo Logo
Gentoo Spaceship




Note: Due to technical difficulties, the Archives are currently not up to date. GMANE provides an alternative service for most mailing lists.
c.f. bug 424647
List Archive: gentoo-doc
Navigation:
Lists: gentoo-doc: < Prev By Thread Next > < Prev By Date Next >
Headers:
To: gentoo-doc@g.o
From: Josh Saddler <nightmorph@g.o>
Subject: Re: Wiki for official docs only
Date: Sat, 18 Jul 2009 19:25:52 -0700
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.

Attachment:
signature.asc (OpenPGP digital signature)
Replies:
Re: Wiki for official docs only
-- Robert Buchholz
References:
Wiki for official docs only
-- AllenJB
Re: Wiki for official docs only
-- Xavier Neys
Re: Wiki for official docs only
-- AllenJB
Navigation:
Lists: gentoo-doc: < Prev By Thread Next > < Prev By Date Next >
Previous by thread:
Re: Wiki for official docs only
Next by thread:
Re: Wiki for official docs only
Previous by date:
Re: Wiki for official docs only
Next by date:
Re: Wiki for official docs only


Updated Apr 08, 2012

Summary: Archive of the gentoo-doc mailing list.

Donate to support our development efforts.

Copyright 2001-2013 Gentoo Foundation, Inc. Questions, Comments? Contact us.