headers
AllenJB | 7 Jul 2009 00:03
Picon

Wiki for official docs only

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.
(Continue reading)

Permalink | Reply | 5 comments |
headers
Xavier Neys | 12 Jul 2009 17:48
Picon
Favicon

Re: Wiki for official docs only

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.

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

--
(Continue reading)

Permalink | Reply | 4 comments |
headers
AllenJB | 13 Jul 2009 00:01
Picon

Re: Wiki for official docs only

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
(Continue reading)

Permalink | Reply | 3 comments |
headers
Josh Saddler | 19 Jul 2009 04:25
Picon
Favicon
Gravatar

Re: Wiki for official docs only

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.
(Continue reading)

Permalink | Reply | 1 comment |
headers
James Robertson | 19 Jul 2009 11:46
Picon
Gravatar

Re: Wiki for official docs only

Keep up the good work team, I prefer Gentoo official docs  over
mediawiki since it's easier to maintain on the back-end.

Perhaps as a happy medium someone could demonstrate how a mediawiki
interface could be used for writing documents which can be converted
into the GuideXML system.

James Robertson (Gentoo enthusiast),
Edinburgh, UK
Permalink | Reply | 0 comments |
headers
Robert Buchholz | 19 Jul 2009 16:23
Picon
Favicon

Re: Wiki for official docs only

Hi Josh,

Josh Saddler <nightmorph <at> gentoo.org> writes:
> > 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.

I for one find Wiki Syntax a lot easier to read since the text-only (source)
version looks not much different from the rendered version. There are two main
advantages to the existing docs:

1) The preview feature is built-in

I have written and edited some GuideXML documents. I have never done so without
making a mistake. Getting the document rendered is a huge hassle (for me). I
need to install a web server and some additions (which I need root for usually).
Or I need to ssh to dev and see the doc there. Images and links will break.

2) The change submission system is built in

This is two sided: To commit something I do not need CVS, saving is built in. I
do not need to prepare unreadable*  patches. I do not need Bugzilla to make a
change, and merging changes is a one-click operation for the wiki editors.
MediaWiki has all these functions built in. Users can sign up, make a change
from anywhere. And the docs team can use the "reviewed revision" feature to hide
changes from others until they are reviewed.
(Continue reading)

Permalink | Reply | 0 comments |

Gmane