thr3ads.net - Xen users - [Xen-users] Push for Better Documentation [Jul 2007]

If this information is useful, please help other people find it:
Share via:

Dylan Martin

2007-Jul-06 21:35 UTC

[Xen-users] Push for Better Documentation

I recently read this article about how xen isn''t turning out to be the
VMware killer we had hoped it would be.  

http://www.interopnews.com/news/desperately-seeking-xen.html

This got me a little worried.  I''d like to stop using VMware and just
use xen, but xen just isn''t ready yet.  

I''m convinced that what we really need is better documentation for
the opensource xen.  

The xen user manual is barely a feature list and it doesn''t cover 3.0.
The wiki is a shambles with some topics covered, many not, and worst
of all, there''s no reasonable organization.  Don''t even get me
started
about the FAQ... 

Without good documentation, you get fewer users, without users, you
have less contribution, without contribution the product stagnates.  

So, then what are we going to do about it?  

I don''t have much time and I''m not a very good writer, but
I''m going
to try to spend some time every day improving the opensource xen docs.

I think I''m going to start by combing through the mail archive and
finding out what questions really are most frequently asked and
creating a new FAQ.  If people like it, we could use it to replace the
sad neglected FAQ that we have today.

I''d also like to suggest to Xensource that they spend some
money hiring a real technical writer to improve the opensource docs.
The improved production from the opensource community would probably
cover that cost many times over.

I''d love to hear from anyone else who is trying to improve the xen
docs or who is interested but hasn''t yet found the time or anyone
with an opinion about the best ways to make improvements.  

Thanks!
-Dylan

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

Nico Kadel-Garcia

2007-Jul-06 22:47 UTC

head link

Re: [Xen-users] Push for Better Documentation

Dylan Martin wrote:> I recently read this article about how xen isn''t turning out to be
the
> VMware killer we had hoped it would be.  
>
> http://www.interopnews.com/news/desperately-seeking-xen.html
>
> This got me a little worried.  I''d like to stop using VMware and
just
> use xen, but xen just isn''t ready yet.  
>
> I''m convinced that what we really need is better documentation for
> the opensource xen.  
>   Amen.
> I think I''m going to start by combing through the mail archive and
> finding out what questions really are most frequently asked and
> creating a new FAQ.  If people like it, we could use it to replace the
> sad neglected FAQ that we have today.
>   Cool. The gold standard I tend to use for such documents is the 
Subversion manual.
> I''d also like to suggest to Xensource that they spend some
> money hiring a real technical writer to improve the opensource docs.
> The improved production from the opensource community would probably
> cover that cost many times over.
>
> I''d love to hear from anyone else who is trying to improve the xen
> docs or who is interested but hasn''t yet found the time or anyone
> with an opinion about the best ways to make improvements.  
>   I might be interested. My current contract is ending July 31. (If anyone 
''s hiring in London, let me know, I''m looking for new
contracts.) I
might have some time to apply to this wile looking for work.

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

Tom Horsley

2007-Jul-06 23:06 UTC

head link

Re: [Xen-users] Push for Better Documentation

On Fri, 6 Jul 2007 14:35:36 -0700
Dylan Martin <dmartin@sccd.ctc.edu> wrote:
> I think I''m going to start by combing through the mail archive and
> finding out what questions really are most frequently asked and
> creating a new FAQ.  If people like it, we could use it to replace the
> sad neglected FAQ that we have today.
A somewhat outdated version of my own personal state of confusion
can be found at:

http://home.att.net/~Tom.Horsley/xen-fci.html

I''ve gradually overcome some of the confusion, but I am
still utterly and completely bereft of any idea about how
to discover what can appear in the disk definitions for
a virtual machine and which drivers have to exist in the
guest to make use of what disk features.

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

Christian Horn

2007-Jul-08 07:53 UTC

head link

Re: [Xen-users] Push for Better Documentation

On Fri, Jul 06, 2007 at 07:06:16PM -0400, Tom Horsley
wrote:> 
> A somewhat outdated version of my own personal state of confusion
> can be found at:
> 
> http://home.att.net/~Tom.Horsley/xen-fci.html
Same can be said on my xen-notes:
http://wiki.fluxcoil.net/doku.php/xen

Wondering if some collective effort could improve the state of the
xen-documentation..

Christian

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

Dylan Martin

2007-Jul-10 00:32 UTC

head link

Re: [Xen-users] Push for Better Documentation

> Wondering if some collective effort could improve the state of the
> xen-documentation..
That''s exactly what I''d like to see!
> On Fri, Jul 06, 2007 at 07:06:16PM -0400, Tom Horsley wrote:
> > 
> > A somewhat outdated version of my own personal state of confusion
> > can be found at:
> > 
> > http://home.att.net/~Tom.Horsley/xen-fci.html
> 
> Same can be said on my xen-notes:
> http://wiki.fluxcoil.net/doku.php/xen
> 
> Wondering if some collective effort could improve the state of the
> xen-documentation..
> 
> Christian
> 
> _______________________________________________
> Xen-users mailing list
> Xen-users@lists.xensource.com
> http://lists.xensource.com/xen-users
_______________________________________________
Xen-users mailing list
Xen-users@lists.xensource.com
http://lists.xensource.com/xen-users

Dylan Martin

2007-Jul-10 00:34 UTC

head link

Re: [Xen-users] Push for Better Documentation

> I might be interested. My current contract is ending July 31. (If anyone 
> ''s hiring in London, let me know, I''m looking for new
contracts.) I
> might have some time to apply to this wile looking for work.
Did you have any ideas of what documentation you might want to work on?  

-Dylan

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

Lev Lafayette

2007-Jul-10 00:45 UTC

head link

Re: [Xen-users] Push for Better Documentation

On Mon, 2007-07-09 at 17:32 -0700, Dylan Martin wrote:> > Wondering if some collective effort could improve the state of the
> > xen-documentation..
> 
> That''s exactly what I''d like to see!
> 
> > On Fri, Jul 06, 2007 at 07:06:16PM -0400, Tom Horsley wrote:
> > > 
> > > A somewhat outdated version of my own personal state of confusion
> > > can be found at:
> > > 
> > > http://home.att.net/~Tom.Horsley/xen-fci.html
> > 
> > Same can be said on my xen-notes:
> > http://wiki.fluxcoil.net/doku.php/xen
> > 
> > Wondering if some collective effort could improve the state of the
> > xen-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,



Lev

* Which also means I''m not terribly fond of the postmodernists.


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

Dylan Martin

2007-Jul-10 01:16 UTC

head link

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@lists.xensource.com
http://lists.xensource.com/xen-users

Artur Linhart - Linux communication

2007-Jul-10 14:32 UTC

head link

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.

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)

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?

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

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

	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.

-----Original Message-----
From: xen-users-bounces@lists.xensource.com
[mailto:xen-users-bounces@lists.xensource.com] On Behalf Of Dylan Martin
Sent: Tuesday, July 10, 2007 3:16 AM
To: Lev Lafayette
Cc: Tom Horsley; Christian Horn; xen-users@lists.xensource.com
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@lists.xensource.com
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@lists.xensource.com
http://lists.xensource.com/xen-users

Nico Kadel-Garcia

2007-Jul-10 16:00 UTC

head link

Re: [Xen-users] Push for Better Documentation

Artur Linhart - Linux communication wrote:> I would propose not to create a new or user-specific pages, but use and
> improve existing structures on the xensource website, especially wiki.
>
> 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)
>   Amen. A consistent list, updated with each major software list, would be 
majorly useful.

> 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?
>   The XenSource RPM''s do not include them. They use a
Latex->HTML->manage
format, which just makes me twitch to see in use. But if you look in the 
Makefile, you''ll see the traces of it.
> 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...
>
> 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...
>
> 	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.
>
> -----Original Message-----
> From: xen-users-bounces@lists.xensource.com
> [mailto:xen-users-bounces@lists.xensource.com] On Behalf Of Dylan Martin
> Sent: Tuesday, July 10, 2007 3:16 AM
> To: Lev Lafayette
> Cc: Tom Horsley; Christian Horn; xen-users@lists.xensource.com
> 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@lists.xensource.com
> 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@lists.xensource.com
> http://lists.xensource.com/xen-users
>
>   

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

Dylan Martin

2007-Jul-10 23:51 UTC

head link

Re: [Xen-users] Push for Better Documentation

> As I suggestion, if you find gaps and new questions and if I work on the
> existing faq then the two could be merged..
> 
> > Does that sound like a good system?  What documentation would you like
> 
> As above; I''ll start by going through existing documentation with
a
> fine-tooth comb...
Sounds great!


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

Dylan Martin

2007-Jul-11 00:32 UTC

head link

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@lists.xensource.com
> [mailto:xen-users-bounces@lists.xensource.com] On Behalf Of Dylan Martin
> Sent: Tuesday, July 10, 2007 3:16 AM
> To: Lev Lafayette
> Cc: Tom Horsley; Christian Horn; xen-users@lists.xensource.com
> 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@lists.xensource.com
> 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@lists.xensource.com
http://lists.xensource.com/xen-users

Artur Linhart - Linux communication

2007-Jul-11 10:18 UTC

head link

RE: [Xen-users] Push for Better Documentation

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@sccd.ctc.edu] 
Sent: Wednesday, July 11, 2007 2:33 AM
To: Artur Linhart - Linux communication
Cc: ''Lev Lafayette''; ''Tom Horsley'';
''Christian Horn'';
xen-users@lists.xensource.com
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@lists.xensource.com
> [mailto:xen-users-bounces@lists.xensource.com] On Behalf Of Dylan Martin
> Sent: Tuesday, July 10, 2007 3:16 AM
> To: Lev Lafayette
> Cc: Tom Horsley; Christian Horn; xen-users@lists.xensource.com
> 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@lists.xensource.com
> 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@lists.xensource.com
http://lists.xensource.com/xen-users

Dylan Martin

2007-Jul-11 16:07 UTC

head link

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@sccd.ctc.edu] 
> Sent: Wednesday, July 11, 2007 2:33 AM
> To: Artur Linhart - Linux communication
> Cc: ''Lev Lafayette''; ''Tom Horsley'';
''Christian Horn'';
> xen-users@lists.xensource.com
> 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@lists.xensource.com
> > [mailto:xen-users-bounces@lists.xensource.com] On Behalf Of Dylan
Martin
> > Sent: Tuesday, July 10, 2007 3:16 AM
> > To: Lev Lafayette
> > Cc: Tom Horsley; Christian Horn; xen-users@lists.xensource.com
> > 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@lists.xensource.com
> > 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@lists.xensource.com
http://lists.xensource.com/xen-users

Dylan Martin

2007-Jul-18 20:25 UTC

head link

Re: [Xen-users] Push for Better Documentation

> 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.
Okay, I said I''d get back to you about this, but I didn''t
think I''d
take this long... ;)

The source for the xen man pages is in pod format.  That''s Plain Old
Documentation.  It''s a really simple format used for perl.  If
you''re
on a unixy box, you can type ''man perlpod'' to read all about
it.
There are different commands to convert pod code to
man,html,text,latex etc... pod2man, pod2html etc..

If you look in the  docs dir in the source tarball, you''ll see
dirs called man, man1, and man5.  The ''man'' dir contains the
pod
files.  Edit those and then run ''make'' from inside the
''docs'' dir.
The new man files will show up in man1 and man5.  To view man files
that aren''t in the system man dirs, you can run "nroff -man
filename |
less"
 
Have fun!
 
-Dylan
> 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... 
It looks like Fedora 7 doesn''t even bother to include the crusty old
man files.  Can''t blame them for that...


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

Dylan Martin

2007-Jul-18 21:44 UTC

head link

Re: [Xen-users] Push for Better Documentation

>    I''m sorry, but please look again. A number of documents  from
the tarball
>    are in *LaTeX*.  It converts the LaTeX documentation into podfiles and
>    turns those into man pages, using /usr/bin/latex, /usr/bin/dot,
>    /usr/bin/ps2pdf, and a variety of other undocumented requirements to
>    rebuild the documentation from their original format.
If you''re only interested in man pages, you only need to worry about
the pod stuff.  The longer docs, like the user guide or the xen-api
doc might be in other formats.  To convert pod to pdf you first
convert it to latex, so that''s part of what you''re seeing.

It looks like the make file only uses tools it finds.  For instance,
it won''t build the python-dev-docs if it doesn''t find doxygen.

So, if you want to edit the man pages, you can do so without worrying
about latex or anything else.
>    Inconsistent document format is a long-standing problem of a lot of
>    projects.
Yes.  I totally agree about this.  It''s a total pain that
they''re not
all written in pod or docbook or some other single format.  You can
always convert between formats, but you should have one canonical
format for your project.

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

Nico Kadel-Garcia

2007-Jul-18 22:00 UTC

head link

Re: [Xen-users] Push for Better Documentation

Dylan Martin wrote:>>    I''m sorry, but please look again. A number of documents 
from the tarball
>>    are in *LaTeX*.  It converts the LaTeX documentation into podfiles
and
>>    turns those into man pages, using /usr/bin/latex, /usr/bin/dot,
>>    /usr/bin/ps2pdf, and a variety of other undocumented requirements to
>>    rebuild the documentation from their original format.
>>     
>
> If you''re only interested in man pages, you only need to worry
about
> the pod stuff.  The longer docs, like the user guide or the xen-api
> doc might be in other formats.  To convert pod to pdf you first
> convert it to latex, so that''s part of what you''re
seeing.
>
> It looks like the make file only uses tools it finds.  For instance,
> it won''t build the python-dev-docs if it doesn''t find
doxygen.
>   I get "make docs" casting errors, and failing. This makes modifying
the
.spec file to build RPM''s rather awkward. The RHEL and Fedora Core 
bundles do a better job of this, I''m afraid.
> So, if you want to edit the man pages, you can do so without worrying
> about latex or anything else.
>   OK, the xenapi documents, for example, seem to be in LaTeX format.
>>    Inconsistent document format is a long-standing problem of a lot of
>>    projects.
>>     
>
> Yes.  I totally agree about this.  It''s a total pain that
they''re not
> all written in pod or docbook or some other single format.  You can
> always convert between formats, but you should have one canonical
> format for your project.Especially when hte LaTeX stuff throws errors, which seem to still 
produce a printable page, but wind up hanging at a LaTeX debugging 
console.....

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

Artur Linhart - Linux communication

2007-Jul-19 11:23 UTC

head link

[Xen-devel] RE: [Xen-users] Push for Better Documentation

OK, thank Zou for information. Do You know something about who is
responsible for the documentation creation etc, or where the developen
"pod"-s are stored and managed (some version control system, etc? I
would be
good to work on documentation of something, what is not yet in processing by
somebody - or work on the themes together...

	With regards

		archie

-----Original Message-----
From: Dylan Martin [mailto:dmartin@sccd.ctc.edu] 
Sent: Wednesday, July 18, 2007 10:26 PM
To: Artur Linhart - Linux communication
Cc: ''Lev Lafayette''; ''Tom Horsley'';
''Christian Horn'';
xen-users@lists.xensource.com
Subject: Re: [Xen-users] Push for Better Documentation
> 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.
Okay, I said I''d get back to you about this, but I didn''t
think I''d
take this long... ;)

The source for the xen man pages is in pod format.  That''s Plain Old
Documentation.  It''s a really simple format used for perl.  If
you''re
on a unixy box, you can type ''man perlpod'' to read all about
it.
There are different commands to convert pod code to
man,html,text,latex etc... pod2man, pod2html etc..

If you look in the  docs dir in the source tarball, you''ll see
dirs called man, man1, and man5.  The ''man'' dir contains the
pod
files.  Edit those and then run ''make'' from inside the
''docs'' dir.
The new man files will show up in man1 and man5.  To view man files
that aren''t in the system man dirs, you can run "nroff -man
filename |
less"
 
Have fun!
 
-Dylan
> 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... 
It looks like Fedora 7 doesn''t even bother to include the crusty old
man files.  Can''t blame them for that...


__________ Informace od NOD32 2405 (20070718) __________

Tato zprava byla proverena antivirovym systemem NOD32.
http://www.nod32.cz



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

Mats Petersson

2007-Jul-19 11:43 UTC

head link

Re: [Xen-devel] RE: [Xen-users] Push for Better Documentation

At 12:23 19/07/2007, Artur Linhart - Linux communication
wrote:>OK, thank Zou for information. Do You know something about who is
>responsible for the documentation creation etc, or where the developen
>"pod"-s are stored and managed (some version control system, etc?
I would be
>good to work on documentation of something, what is not yet in processing by
>somebody - or work on the themes together...

The docs are part of the Xen "source code", so if you grab the Xen 
source tarball, or install "mercurial" (hg)[1] and do "hg clone 
http://xenbits.xensource.com/xen-unstable".

Using mercurial is the best way, since that means that you can:
1) Generate patches from your changes without keeping a second copy 
of everything you may want to change [2].
2) Update your current source-directory to the latest unstable 
sources with "hg pull && hg update"
3) Roll back your changes if you decide that you haven''t "done the
right changes" [e.g. when you do "too many fingers on keyboard"
in
the editor and end up with half the file missing and no backup file]. 
You can even keep your own local set of changes and thus have a 
history of what you''ve done, and then export all changes as one
patch-set.

[1] Here''s the first place google found for downloading mercurial: 
http://linux.softpedia.com/get/Programming/Version-Control/Mercurial-9329.shtml

[2] Of course there is a second copy, but it''s automatically 
maintained by mercurial rather than by manually. The drawback here is 
that since mercurial keeps ALL the changes, the "second copy" is 
quite a bit larger than the whole Xen source-tree - but it is 
compressed, so not that bad, and in a place where disk-space is 
counted in tens or hundreds of gigabytes, it''s not a real problem.

--
Mats

>         With regards
>
>                 archie
>
>-----Original Message-----
>From: Dylan Martin [mailto:dmartin@sccd.ctc.edu]
>Sent: Wednesday, July 18, 2007 10:26 PM
>To: Artur Linhart - Linux communication
>Cc: ''Lev Lafayette''; ''Tom Horsley'';
''Christian Horn'';
>xen-users@lists.xensource.com
>Subject: Re: [Xen-users] Push for Better Documentation
>
> > 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.
>
>Okay, I said I''d get back to you about this, but I didn''t
think I''d
>take this long... ;)
>
>The source for the xen man pages is in pod format.  That''s Plain
Old
>Documentation.  It''s a really simple format used for perl.  If
you''re
>on a unixy box, you can type ''man perlpod'' to read all
about it.
>There are different commands to convert pod code to
>man,html,text,latex etc... pod2man, pod2html etc..
>
>If you look in the  docs dir in the source tarball, you''ll see
>dirs called man, man1, and man5.  The ''man'' dir contains
the pod
>files.  Edit those and then run ''make'' from inside the
''docs'' dir.
>The new man files will show up in man1 and man5.  To view man files
>that aren''t in the system man dirs, you can run "nroff -man
filename |
>less"
>
>Have fun!
>
>-Dylan
>
> > 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...
>
>It looks like Fedora 7 doesn''t even bother to include the crusty
old
>man files.  Can''t blame them for that...
>
>
>__________ Informace od NOD32 2405 (20070718) __________
>
>Tato zprava byla proverena antivirovym systemem NOD32.
>http://www.nod32.cz
>
>
>
>_______________________________________________
>Xen-devel mailing list
>Xen-devel@lists.xensource.com
>http://lists.xensource.com/xen-devel

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

Xen users - Jul 2007 - Push for Better Documentation

[Xen-users] Push for Better Documentation

Re: [Xen-users] Push for Better Documentation

Re: [Xen-users] Push for Better Documentation

Re: [Xen-users] Push for Better Documentation

Re: [Xen-users] Push for Better Documentation

Re: [Xen-users] Push for Better Documentation

Re: [Xen-users] Push for Better Documentation

Re: [Xen-users] Push for Better Documentation

RE: [Xen-users] Push for Better Documentation

Re: [Xen-users] Push for Better Documentation

Re: [Xen-users] Push for Better Documentation

Re: [Xen-users] Push for Better Documentation

RE: [Xen-users] Push for Better Documentation

Re: [Xen-users] Push for Better Documentation

Re: [Xen-users] Push for Better Documentation

Re: [Xen-users] Push for Better Documentation

Re: [Xen-users] Push for Better Documentation

[Xen-devel] RE: [Xen-users] Push for Better Documentation

Re: [Xen-devel] RE: [Xen-users] Push for Better Documentation