Xen devel - Nov 2005 - two possible approaches for quicker, more accessible documentation development

Good evening.

Would it be feasible for Xen to adopt some documentation processes
similar to that of PHP or CVS?

(1) PHP has documentation in web pages with an opportunity for readers
to post comments at the end of each page:

http://www.php.net/manual/en/

(2) Ximbiot has produced a Wiki version of the entire CVS manual ("The
Cedverquist"):

http://ximbiot.com/cvs/manual/

I realize that Xen already has a thriving Wiki, but would really like to
be able to make small comments to the documentation as conveniently as I
can for these other projects.

This could also help with community-based translation efforts.

Andrew




_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Andrew,

Thanks for the suggestion.

It looks like the PHP manual is built around DocBook (a widely-used XML
DTD), with some mechanism that they have built for collecting comments
at the end of each page. I am moving in the direction of using DocBook
for my source docs. I think that model of being able to collect comments
on a per-section basis is really good and I will look into what it would
take to set such a system up here.

Cheers...

-Alan

Alan C. Oehler
Sr. Technical Writer
XenSource, Inc.
Phone: 650.798.5900 x 240


_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel

Ewan Mellor pointed out to me yesterday that this particular model
(having a world-postable comments section at the end of each chapter or
section, ala the PHP manual or the CVS manual) could end up being
littered with bad advice, poor  examples, etc. To make this kind of
thing work well we would have to either hope that all the comments were
valuable and helpful, or vet the comments carefully on a regular basis.

-Alan

Alan C. Oehler
Sr. Technical Writer
XenSource, Inc.
Phone: 650.798.5900 x 240

> -----Original Message-----
> From: xen-devel-bounces@lists.xensource.com 
> [mailto:xen-devel-bounces@lists.xensource.com] On Behalf Of 
> xen-devel-request@lists.xensource.com
> Sent: Tuesday, November 15, 2005 5:56 PM
> To: xen-devel@lists.xensource.com
> Subject: Xen-devel Digest, Vol 9, Issue 115
> 
> Send Xen-devel mailing list submissions to
> 	xen-devel@lists.xensource.com
> 
> To subscribe or unsubscribe via the World Wide Web, visit
> 	http://lists.xensource.com/cgi-bin/mailman/listinfo/xen-devel
> or, via email, send a message with subject or body ''help''
to
> 	xen-devel-request@lists.xensource.com
> 
> You can reach the person managing the list at
> 	xen-devel-owner@lists.xensource.com
> Date: Tue, 15 Nov 2005 14:44:15 -0800
> From: "Alan C. Oehler" <alan@xensource.com>
> Subject: [Xen-devel] two possible approaches for quicker,	more
> 	accessible documentation development
> To: <xen-devel@lists.xensource.com>
> Message-ID:
> 	
> <40F951C7DA13C0428B4A1846E7B204F38274DF@xenexchange.xensource.com>
> Content-Type: text/plain;	charset="us-ascii"
> 
> Andrew,
> 
> Thanks for the suggestion.
> 
> It looks like the PHP manual is built around DocBook (a 
> widely-used XML DTD), with some mechanism that they have 
> built for collecting comments at the end of each page. I am 
> moving in the direction of using DocBook for my source docs. 
> I think that model of being able to collect comments on a 
> per-section basis is really good and I will look into what it 
> would take to set such a system up here.
> 
> Cheers...
> 
> -Alan
> 
> Alan C. Oehler
> Sr. Technical Writer
> XenSource, Inc.
> Phone: 650.798.5900 x 240
> 
_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel