Re: [Xen-users] Push for Better Documentation

[Dylan Martin <dmartin@xxxxxxxxxxxx>]

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

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