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
[email protected]
http://lists.xen.org/cgi-bin/mailman/listinfo/xen-api
