[Xen-devel] RE: two possible approaches for quicker, more accessible documentation development

["Alan C. Oehler" <alan@xxxxxxxxxxxxx>]

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@xxxxxxxxxxxxxxxxxxx 
> [mailto:xen-devel-bounces@xxxxxxxxxxxxxxxxxxx] On Behalf Of 
> xen-devel-request@xxxxxxxxxxxxxxxxxxx
> Sent: Tuesday, November 15, 2005 5:56 PM
> To: xen-devel@xxxxxxxxxxxxxxxxxxx
> Subject: Xen-devel Digest, Vol 9, Issue 115
> 
> Send Xen-devel mailing list submissions to
>       xen-devel@xxxxxxxxxxxxxxxxxxx
> 
> 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@xxxxxxxxxxxxxxxxxxx
> 
> You can reach the person managing the list at
>       xen-devel-owner@xxxxxxxxxxxxxxxxxxx
> Date: Tue, 15 Nov 2005 14:44:15 -0800
> From: "Alan C. Oehler" <alan@xxxxxxxxxxxxx>
> Subject: [Xen-devel] two possible approaches for quicker,     more
>       accessible documentation development
> To: <xen-devel@xxxxxxxxxxxxxxxxxxx>
> Message-ID:
>       
> <40F951C7DA13C0428B4A1846E7B204F38274DF@xxxxxxxxxxxxxxxxxxxxxxxxx>
> 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@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-devel