sec=unclassified RE: The value of separating the doc wiki

[Stoffers, Robert LAC]

> A lot of what I have learned so far comes either from the Wiki or in the
> case of Docbook, copying what someone else has done.  For those people who
> have just started contribuing to the docs, did it really take that much
> effort to learn Docbook?

The point is that Guide XML is a lot easier to learn to Docbook, thus the learning curve for new contributors is greatly lessened. The Guide XML syntax resembles HTML a lot closer and doing more advanced things such as linking several documents/between documents is made easier also.

I'm not saying we should instantly change right before release. A while back there was discussion as to why Gentoo documentation was regarded as good, and what Ubuntu could learn from it. Since then I have been doing some poking around and what I found I posted my thoughts on earlier. The Gentoo docteam has gone to great lengths to make it as easy as possible for anyone to contribute, not just those few willing to learn Docbook. This has everything to do with lessening the pain for everyone involved, getting the users to actually write documentation rather then just some random thoughts on the wiki (that might be seen if lucky by someone writing the docs).

This might also lessen the occurrence of "unofficial" documentation projects out there also. If to contribute to official documentation all they need to do is:

1. Open browser
2. Navigate to document
3. Click the "view source" link
4. Save to hard drive, edit
5. Run one simple patch command, email the output to ubuntu-doc at lists.ubuntu.com

then they might be more inclined to actually contribute to official documentation instead. This could be done with Docbook too, however using Guide will make it even easier for the new contributor to get into it. 

I'm going to put together some sample code (python/php) if I get the time soon.

Regards,

Robert Stoffers
rob1 at ubuntu.com