Gentoo Archives: gentoo-doc

From: AllenJB <gentoo-lists@××××××××××.uk>
To: gentoo-doc@l.g.o
Subject: Re: [gentoo-doc] Wiki for official docs only
Date: Sun, 12 Jul 2009 22:01:27
In Reply to: Re: [gentoo-doc] Wiki for official docs only by Xavier Neys
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


Subject Author
Re: [gentoo-doc] Wiki for official docs only Josh Saddler <nightmorph@g.o>
Re: [gentoo-doc] Wiki for official docs only James Robertson <james@××××××××××××.uk>