Xen devel - Sep 2012 - Proposal - Add xe manpages to xen-org

Xen Community,

    I have a team of people frantically creating manpages for the xe
command and all of it''s 361 subcommands. The initial source
documentation
is in asciidoc but also saved as Docbook. From docbook we transform to
epub, html, manpage and pdf. This is currently being hosted in a subversion
server at a Seattle area college and we''d like to move it to the
xen-org
github so it''s public, can be reviewed, commented on and contributed
too.

We will also document the additional commands specific to xenserver/xcp
(xe-edit-bootloader and others like it as time permits.

For each section of commands we''re also writing xcp tools that describe
how
to script the xe command and use it''s various options/parameters. These
tools have been a godsend in our own administration so far and should be
packages and distributed themselves.

All of our documentation is created with future XSLT transforms being able
to include or remove sections with the Administration guide and xe help in
mind.

This is an official proposal to add this project to xen-org.


Grant McWilliams
Professor of Computer Science
Edmonds Community College

Grant,

this sounds like a fantastic idea. I will leave this for community 
discussion for now, and follow-up whether we need a formal vote in about 
a week''s time. I guess there is also some detail to sort out such as 
repo name, exact location, anything legal (e.g. does the source have GPL 
headers), etc.

Best Regards
Lars

On 24/09/2012 16:06, Grant McWilliams wrote:
> Xen Community,
>
>     I have a team of people frantically creating manpages for the xe 
> command and all of it''s 361 subcommands. The initial source 
> documentation is in asciidoc but also saved as Docbook. From docbook 
> we transform to epub, html, manpage and pdf. This is currently being 
> hosted in a subversion server at a Seattle area college and we''d
like
> to move it to the xen-org github so it''s public, can be reviewed, 
> commented on and contributed too.
>
> We will also document the additional commands specific to 
> xenserver/xcp (xe-edit-bootloader and others like it as time permits.
>
> For each section of commands we''re also writing xcp tools that 
> describe how to script the xe command and use it''s various 
> options/parameters. These tools have been a godsend in our own 
> administration so far and should be packages and distributed themselves.
>
> All of our documentation is created with future XSLT transforms being 
> able to include or remove sections with the Administration guide and 
> xe help in mind.
>
> This is an official proposal to add this project to xen-org.
>
>
> Grant McWilliams
> Professor of Computer Science
> Edmonds Community College
>

On Mon, 2012-09-24 at 16:21 +0100, Lars Kurth wrote:
> On 24/09/2012 16:06, Grant McWilliams wrote:
> > Xen Community,
> >
> >     I have a team of people frantically creating manpages for the xe 
> > command and all of it''s 361 subcommands. The initial source 
> > documentation is in asciidoc but also saved as Docbook. From docbook 
> > we transform to epub, html, manpage and pdf. This is currently being 
> > hosted in a subversion server at a Seattle area college and
we''d like
> > to move it to the xen-org github so it''s public, can be
reviewed,
> > commented on and contributed too.
IME the best way to ensure that documentation remains current as the
code base changes is to check it in next to the code in the same repo.

This requires a little bit of discipline from the maintainers, to
remember to request appropriate docs updates when code patches require
them, but has been pretty effective e.g. for the xen-unstable code base.

Ian.

On 25 Sep 2012, at 04:22, Ian Campbell
<Ian.Campbell-Sxgqhf6Nn4DQT0dZR+AlfA@public.gmane.org> wrote:
> On Mon, 2012-09-24 at 16:21 +0100, Lars Kurth wrote:
>> On 24/09/2012 16:06, Grant McWilliams wrote:
>>> Xen Community,
>>> 
>>>    I have a team of people frantically creating manpages for the xe
>>> command and all of it''s 361 subcommands. The initial
source
>>> documentation is in asciidoc but also saved as Docbook. From
docbook
>>> we transform to epub, html, manpage and pdf. This is currently
being
>>> hosted in a subversion server at a Seattle area college and
we''d like
>>> to move it to the xen-org github so it''s public, can be
reviewed,
>>> commented on and contributed too.
> 
> IME the best way to ensure that documentation remains current as the
> code base changes is to check it in next to the code in the same repo.
> 
> This requires a little bit of discipline from the maintainers, to
> remember to request appropriate docs updates when code patches require
> them, but has been pretty effective e.g. for the xen-unstable code base.
While xe man-pages are sorely needed, wouldn''t it be better to
autogenerate
it from the existing xe/xapi help by converting it to groff/asciidoc?
Manually keeping the zillion commands in sync will be quite the ongoing 
effort.

-anil

On Tue, 2012-09-25 at 15:19 +0100, Anil Madhavapeddy
wrote:
> On 25 Sep 2012, at 04:22, Ian Campbell
<Ian.Campbell-Sxgqhf6Nn4DQT0dZR+AlfA@public.gmane.org> wrote:
> 
> > On Mon, 2012-09-24 at 16:21 +0100, Lars Kurth wrote:
> >> On 24/09/2012 16:06, Grant McWilliams wrote:
> >>> Xen Community,
> >>> 
> >>>    I have a team of people frantically creating manpages for
the xe
> >>> command and all of it''s 361 subcommands. The initial
source
> >>> documentation is in asciidoc but also saved as Docbook. From
docbook
> >>> we transform to epub, html, manpage and pdf. This is currently
being
> >>> hosted in a subversion server at a Seattle area college and
we''d like
> >>> to move it to the xen-org github so it''s public, can
be reviewed,
> >>> commented on and contributed too.
> > 
> > IME the best way to ensure that documentation remains current as the
> > code base changes is to check it in next to the code in the same repo.
> > 
> > This requires a little bit of discipline from the maintainers, to
> > remember to request appropriate docs updates when code patches require
> > them, but has been pretty effective e.g. for the xen-unstable code
base.
> 
> While xe man-pages are sorely needed, wouldn''t it be better to
autogenerate
> it from the existing xe/xapi help by converting it to groff/asciidoc?
According to the original mail it is in asciidoc already, so maybe this
is already the case?

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.

Ian.

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

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

On Tue, Sep 25, 2012 at 9:01 AM, Ian Campbell
<Ian.Campbell-Sxgqhf6Nn4DQT0dZR+AlfA@public.gmane.org>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