On Tue, Sep 25, 2012 at 9:01 AM, Ian Campbell <[email protected]>wrote: > > 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. >
I agree a directory within xen-api would be great. > 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. > The way I see it is we can create documentation for the xe help command in source code the way it's done now (I'm guessing) and export that to man pages or we can go the other way around. The way I'd envisioned this is we create the ALL documentation in asciidoc which gets transformed into Docbook. From Docbook we can use XSLT to make anything we want including Admin Guide, manpages and xe help. We can export only the sections we need and in the format we need so for xe help we could include only NAME, SYNOPSIS and DESCRIPTION whereas for manpages we'd include all sections etc... I'd need to know more about how the current xe help is created to know if we could transform to that. This way it keeps the documentation people writing in a publishing system they know and the coders could either jump over to xen-api github and update the docs when needed or they could ping the people maintaining them. This is all theory of course. Grant McWilliams
_______________________________________________ Xen-api mailing list [email protected] http://lists.xen.org/cgi-bin/mailman/listinfo/xen-api
