Gentoo Archives: gentoo-doc

From: AllenJB <gentoo-lists@××××××××××.uk>
To: gentoo-doc@l.g.o
Subject: [gentoo-doc] Wiki for official docs only
Date: Mon, 06 Jul 2009 22:03:26
Message-Id: 4A5274A7.6010704@allenjb.me.uk
Hi all,

I know an official Gentoo Wiki has been discussed fairly recently, but
I'd like to throw a different spin out: A wiki for official
documentation (handbooks, other guides) only.

The wiki would only be editable by Gentoo Devs. For authentication, I'd
be surprised if there's not an extension that can hook into the existing
LDAP or whatever databases.

The basic idea is to replace the current documentation with something
that's much easier to edit.

I recently looked at editing the handbooks to provide patches to update
them for autobuilds, death of GRP, using "eselect profile" for profile
management, etc. My problem is I have limited time, and while I have
tackled GuideXML in the past, it's not something I enjoy doing at all -
I have to lookup the syntax every time and double check everything. On
top of that the Handbooks in particular are (at a glance) a maze of
multiple files pieced together into the finished product (I haven't got
round to checking whether this maze is mapped out anywhere yet - I had
multiple things on my todo list at the time and decided to just move on
to the next item).

On the other hand, I (and I suspect a large number of other people in
general) use wiki's quite a lot, am familiar with the syntax and find
them a breeze to edit. In my opinion, it is likely the the official
documentation would receive more, faster contributions if they were on a
wiki instead of built using GuideXML.

Providing static copies shouldn't be an issue. There are various
extensions to provide wiki documents in various formats and I believe
that, if a system doesn't already exist, one could be built relatively
easily, to allow automatic generation of static versions.

I think that even if some documentation ends up having to be duplicated
(eg. between the x86 and amd64 handbooks), the losses through such
duplication would be outweighed by improved contributions.

I haven't mentioned an engine at all, but I'd suggest mediawiki because
it's popular, has a lot of extensions already available and the syntax
is familiar to many.

Thoughts? Concerns?

AllenJB

Replies

Subject Author
Re: [gentoo-doc] Wiki for official docs only Xavier Neys <neysx@g.o>