Re: [Xen-devel] Proposal - Add xe manpages to xen-org

[Lars Kurth <lars.kurth-LM2mM/qkH7s@public.gmane.org>]

On 25/09/2012 15:30, Ian Campbell wrote:
> According to the original mail it is in asciidoc already, so maybe 
> this is already the case?
My understanding is that the existing XenServer/XCP docs are primarily 
task driven (i.e. “to achieve X you do Y”). Man pages are per command 
references (i.e. “doing Y will cause X to happen”), which is hardly 
covered in
existing XS documentation.

> I agree that actually in the source is even better than next to the
> source, if it's an option...
>
>> Manually keeping the zillion commands in sync will be quite the ongoing
>> effort.
> Someone still needs to write/update the text regardless of where it
> lives, but that's as much a code review thing as anything else.
>
I wouldn't want to create a barrier for Grant's students (or other 
people that want to contribute). Remember that most are not developers 
but users of XCP.  Embedding the documentation into the code would mean:
a) existing document source code would need to be refactored
b) it would create a psychological barrier to contribute
c) possibly unnecessary process

Keeping the documentation separate (either in a separate repo, or 
directory in an existing repo) is probably the easiest and quickest way 
to get this project off the ground quickly.

Lars




_______________________________________________
Xen-api mailing list
Xen-api@lists.xen.org
http://lists.xen.org/cgi-bin/mailman/listinfo/xen-api