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

[Ian Campbell <Ian.Campbell@xxxxxxxxxx>]

On Tue, 2012-09-25 at 16:53 +0100, Lars Kurth wrote:
> 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.

That may all be true. But I was talking about about the docs which Grant
has produced, which he said were in asciidoc.

> > 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.

In which case I would suggest a directory of the existing xen-api repo
and not a completely separate one.

BTW, I wasn't suggesting that people contributing docs needed to become
code contributors too. Only the inverse which is that people changing
the code should be expect to simultaneously update any docs relevant to
their change. Obviously it is also fine to improve the docs without
changing the code.

Ian.


_______________________________________________
Xen-devel mailing list
Xen-devel@xxxxxxxxxxxxx
http://lists.xen.org/xen-devel