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

[AllenJB]

Xavier Neys wrote:
> AllenJB wrote:
>
>> The basic idea is to replace the current documentation with something
>> that's much easier to edit.
>>
>
>> 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).
>
> Easy, refresh your anoncvs, create a debug.xml file in your document
> root that contains
> <debug on="1"/>
>
> and voilà, you see the file names.

Thanks for the tip.

>
>> 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.
>
> In other words, you want the current docs team to learn a new syntax and
> a new tool, and infra to install a new system because you can't learn a
> dozen simple tags, you know like <p> for a paragraph...
>
>
> Wkr,

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!)

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)? It might be an idea to do a quick survey before
claiming the entire team would have to learn a new syntax - you might
find that everyone on the docs team is already familiar with mediawiki.
Even if they're not, mediawiki syntax is extremely well documented and
easy to learn, in my experience.

At the end up the day, this is a suggestion. I've made the suggestion
because I think that the way Gentoo documentation currently works (ie.
because it's written in GuideXML) is cumbersome and makes it difficult
to easily pick up. I believe this has led to a lack of volunteers with
the available time and inclination to learn GuideXML just for Gentoo
documentation work, which has led to the current situation with sorely
needed handbook updates not getting done in a timely manner.

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.

Having a mediawiki based setup would, in my opinion, allow newbies to
get involved much more quickly. A local install of mediawiki and apache
takes literally minutes. A "fast" install would be something like:
1) emerge apache mediawiki;
2) Create database (& db user) (I think instructions for this are in the
post-install for mediawiki);
3) Configure mediawiki using the included wizard). You can easily export
content from one wiki to import to another.

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

(Sorry if that's a bit long-winded. It started as a 2 paragraph reply
and kept growing =o  )

AllenJB