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

[Lars Kurth <lars.kurth@xxxxxxx>]

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@xxxxxxxxxxxxx
http://lists.xen.org/cgi-bin/mailman/listinfo/xen-api