Re: [Xen-users] Push for Better Documentation

[Dylan Martin <dmartin@xxxxxxxxxxxx>]

I'm running the xen that comes with Fedora.  They must have installed
the man pages.  I'll have a look at the man pages in the source and
see if I can find an easy way to edit them.

-Dylan

> Hello,
> 
>       Thank You for the command 
>       'xm create --help_config'
> I did not know it :-) You can put it into the FAQ as tha fast way how to
> figure out the configuration options...
> 
> I would help with it, but I never wrote some manual pages and have zero
> know-how about it... Right now I do not know if there are some tools for
> writing of man pages.
> 
> Where did You get even the old manual pages? In the binary tarball there is
> the directory /usr/share/man with the subdirs man1 and man8, but there are 
> Only 3 fragments (for example nothing about xm) and that's it...
> 
>       With regards,
> 
>               Archie
> 
> -----Original Message-----
> From: Dylan Martin [mailto:dmartin@xxxxxxxxxxxx] 
> Sent: Wednesday, July 11, 2007 2:33 AM
> To: Artur Linhart - Linux communication
> Cc: 'Lev Lafayette'; 'Tom Horsley'; 'Christian Horn';
> xen-users@xxxxxxxxxxxxxxxxxxx
> Subject: Re: [Xen-users] Push for Better Documentation
> 
> > I would propose not to create a new or user-specific pages, but use and
> > improve existing structures on the xensource website, especially wiki.
> 
> Agreed.
>  
> > I personally miss following information:
> > 1. all possible tags and keys in the configuration file for the DomU - I
> > think there are a lot of "hidden functions" which cannot be used because
> > nobody knows them - maybe if they are not implemented fully, they should
> be
> > listed with the corresponding comment what can be expected there ( - for
> > example like the "rate" property of the vif interface definition which has
> > been communicated here some days ago)
> 
> Yes!  I think a great easy first step would be to take the output from
> 'xm create --help_config' and include that in the xm man pages.  You
> could probably make a patch and submit it to xen-devel.  
> 
> > 2. manual pages should be installed together with xen open source - I do
> not
> > if I missed something somewhere, but after installing xen the command "man
> > xm" or silmilar commands return no available manual pages - can this one
> be
> > obtained somwhere?
> 
> Weird.  I got a xm man page with my Fedora, but it's out of date and
> lacks most config file options.  The example configs are much more
> helpful.  Again, info from the examples could be added to the man
> pages.
> 
> Also, since HVM uses QEMU for most of the device stuff, it would be
> nice to have either info for the QEMU settings or at least a note that
> says 'see the QEMU docs' 
> 
> Would you be interested in patching the man files and posting the
> patches to xen-devel?
> 
> > 3. More philosophy-related documents - there are some of them, but it is
> > mainly some basic documentation - are there any documentations which could
> > be taken from the development side? I think there must be such documents,
> > but are not on the xen site...
> 
> I haven't seen many.  What do you mean by 'philosophy'?  Are you
> talking about best practices or something else?
> 
> > But I think, crucial point is to establish the cooperation with the people
> > who develop xen to get the information how it behaves, which functionality
> > is really there in which state (concretely, not only as a list of the
> > features for some release) etc.
> >
> > Is there some authority, which leads the development? I think this
> authority
> > should also be responsible (or delegate to somebody the responsibility)
> for
> > the proper documentation to the users. 
> > To develop functionality does not help, if nobody knows how to use it...
> 
> Yeah.  I'm hoping to get some momentum on fixing the wiki and other
> docs.  I figure there's a ton of work we can do now, and once we do it
> they'll know we're serious so they'll be ready to spend more time
> talking to us.  Of course I could be wrong and they might want to talk
> to us right now... 
> 
> > 
> >     With best regards
> > 
> >             Artur.
> > 
> > P.S. I do not have a lot of time, but would also like to help in this area
> > if this will be possible.
> 
> I don't have much time either.  I'm trying to put in about a 1/2 hr a
> day.  The documentation is in such sad shape, every little bit helps.
> 
> > -----Original Message-----
> > From: xen-users-bounces@xxxxxxxxxxxxxxxxxxx
> > [mailto:xen-users-bounces@xxxxxxxxxxxxxxxxxxx] On Behalf Of Dylan Martin
> > Sent: Tuesday, July 10, 2007 3:16 AM
> > To: Lev Lafayette
> > Cc: Tom Horsley; Christian Horn; xen-users@xxxxxxxxxxxxxxxxxxx
> > Subject: Re: [Xen-users] Push for Better Documentation
> > 
> > > I'm happy to work on this as well. I've recently compiled a fair few
> > > notes on Xen and have given introductory presentations on the subject.
> > > 
> > > Plus, I'm a social sciences graduate. Which means I'm used to writing
> > > 1500+ coherent* words in a single sitting ;-)
> > > 
> > > Shall we start with what constitutes "official" documentation? Are we
> > > going to adopt a manual or wiki approach?
> > > 
> > > All the best,
> > > 
> > > * Which also means I'm not terribly fond of the postmodernists.
> > 
> > Awesome!  
> > 
> > I was thinking we should overhaul the existing wiki, rather than
> > trying to make a competing resource. 
> > 
> > I'm working on FAQ 2.0.  Right now I'm researching what the actual
> > frequently asked questions are.  Once I get something started, I'll
> > post it on the wiki as faq2 or something like that.  Then, if people
> > like it, I'll replace the current faq with my new faq.  
> > 
> > Does that sound like a good system?  What documentation would you like
> > to work on?
> > 
> > Again, Awesome!
> > 
> > -Dylan
> > 
> > P.S. I am also a social science graduate, but I can't write more than
> > 5 coherent words at all...
> > 
> > 
> > 
> >  
> > 
> > _______________________________________________
> > Xen-users mailing list
> > Xen-users@xxxxxxxxxxxxxxxxxxx
> > http://lists.xensource.com/xen-users
> > 
> > __________ Informace od NOD32 2388 (20070710) __________
> > 
> > Tato zprava byla proverena antivirovym systemem NOD32.
> > http://www.nod32.cz
> > 
> > 
> 
> 
> __________ Informace od NOD32 2390 (20070710) __________
> 
> Tato zprava byla proverena antivirovym systemem NOD32.
> http://www.nod32.cz
> 
> 

_______________________________________________
Xen-users mailing list
Xen-users@xxxxxxxxxxxxxxxxxxx
http://lists.xensource.com/xen-users