WARNING - OLD ARCHIVES

This is an archived copy of the Xen.org mailing list, which we have preserved to ensure that existing links to archives are not broken. The live archive, which contains the latest emails, can be found at http://lists.xen.org/
   
 
 
Xen 
 
Home Products Support Community News
 
   
 

xen-users

Re: [Xen-users] Push for Better Documentation

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