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: AllenJB <gentoo-lists@...>
Subject: Wiki for official docs only
Date: Mon, 06 Jul 2009 23:03:19 +0100
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:
Re: Wiki for official docs only
-- Xavier Neys
Navigation:
Lists: gentoo-doc: < Prev By Thread Next > < Prev By Date Next >
Previous by thread:
X Server Configuration Guide Suggestion
Next by thread:
Re: Wiki for official docs only
Previous by date:
Re: X Server Configuration Guide Suggestion
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.