From mboxrd@z Thu Jan 1 00:00:00 1970 From: Joseph Glanville Subject: Re: Xen document day (Oct 12 or 26) Date: Thu, 29 Sep 2011 20:53:47 +1000 Message-ID: References: <20110922130618.GA13238@phenom.oracle.com> <20110922174002.GA1205@phenom.oracle.com> <20098.1097.824552.541924@mariner.uk.xensource.com> <1317195656.13424.73.camel@dagon.hellion.org.uk> <20099.8327.326129.357335@mariner.uk.xensource.com> <20110928134800.GH10270@phenom.oracle.com> <1317218459.26672.62.camel@zakaz.uk.xensource.com> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="===============0765242288==" Return-path: In-Reply-To: <1317218459.26672.62.camel@zakaz.uk.xensource.com> List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Sender: xen-devel-bounces@lists.xensource.com Errors-To: xen-devel-bounces@lists.xensource.com To: Ian Campbell Cc: Daniel Castro , "xen-devel@lists.xensource.com" , Ian Jackson , Konrad Rzeszutek Wilk List-Id: xen-devel@lists.xenproject.org --===============0765242288== Content-Type: multipart/alternative; boundary=00151773e028c0e3b204ae12527d --00151773e028c0e3b204ae12527d Content-Type: text/plain; charset=ISO-8859-1 +1 for Markdown. In terms of making Xen more accessible I think it might be a good idea to update/cleanup the distro support page. http://wiki.xen.org/xenwiki/DistributionSupport I can probably do this. Making it simple for people to get started with Xen on a distro they are comfortable with is a good step forward. I know distro specific guides could turn into a nightmare but I am open to writing one for Debian 6 Squeeze, there are also a few that exist already for RHEL/CentOS on the wiki. This should get easier as more distros update to 3.0+ kernels that support PVops out of the box... Next would be networking documentation as network-bridge script has been deprecated. http://wiki.xensource.com/xenwiki/XenNetworking Once again I think alot of the documentation is going to be distro specific to be newbie friendly but atleast a simple ip/brctl guide would help. IMO knowing where to start and setting up networking were the biggest barriers when I was picking up Xen a few years back. I am also open to updating the blktap2 pages and README to reflect the new tap-ctl userspace utilities and tips on driver development. With jailtime.org(stacklet) now charging for subscription there is nowhere to download pre-built clean Xen compatible images free of charge etc. I have pvgrub/pygrub capable images of Ubuntu/Debian/CentOS that I am considering hosting for free. Generally new users are confused on how to build new paravirt VMs, I think prebuilt images are suboptimal but a good place to start for beginners. Joseph. On 29 September 2011 00:00, Ian Campbell wrote: > On Wed, 2011-09-28 at 14:48 +0100, Konrad Rzeszutek Wilk wrote: > > On Wed, Sep 28, 2011 at 02:26:31PM +0100, Ian Jackson wrote: > > > Ian Campbell writes ("Re: [Xen-devel] Xen document day (Oct 12 or > 26)"): > > > > Since the guest APIs are stable there should be relatively little > churn > > > > so perhaps a wiki page (or even series of pages) would be appropriate > > > > for this sort of thing? > > > > > > I want this to be in-tree. If it's in-tree, we can refuse patches > > > which do not update the documentation. > > > > > > > I think this would be good too and in fact even more important than > the > > > > interface documentation. Everyone needs to be able to build Xen to > hack > > > > on it but only a subset need to know any particular API. > > > > > > > > Also although we recommend that users consume Xen via their distro > where > > > > possible such a guide would also help any who would rather build from > > > > scratch (e.g. because we've asked them to "try the latest version" or > to > > > > bisect a bug etc). > > > > > > This would be a good candidate for a wiki page, backed up by revisions > > > of the in-tree README. > > > > > > Any recommendations on what would be a good format to write these > "interface" > > pages in? > > For in-line (i.e. in xen/include/public/*.h) docs of APIs I played a > little bit with integrating kernel-doc into the Xen build system but it > is tied a little too closely to the kernel build infrastructure. > > Doxygen seems like a plausible alternative with life outside the kernel > etc. We actually appear to already have some doxygen stuff for the > pytyhon stuff (judging from the Makefile, I've not actually noticed the > structured code comments anywhere) > > For non-inline docs I think we decided that markdown would be a good > answer. > > Ian. > > > _______________________________________________ > Xen-devel mailing list > Xen-devel@lists.xensource.com > http://lists.xensource.com/xen-devel > -- * Founder | Director | VP Research Orion Virtualisation Solutions* | www.orionvm.com.au | Phone: 1300 56 99 52 | Mobile: 0428 754 846 --00151773e028c0e3b204ae12527d Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable +1 for Markdown.

In terms of making Xen more accessible I think it m= ight be a good idea to update/cleanup the distro support page.
http://wiki.xen.org/xe= nwiki/DistributionSupport

I can probably do this.
Making it simple for people to get started w= ith Xen on a distro they are comfortable with is a good step forward.
I = know distro specific guides could turn into a nightmare but I am open to wr= iting one for Debian 6 Squeeze, there are also a few that exist already for= RHEL/CentOS on the wiki.
This should get easier as more distros update to 3.0+ kernels that support = PVops out of the box...

Next would be networking documentation as ne= twork-bridge script has been deprecated.
http://wiki.xensource.com/xenwiki/XenNetworkin= g
Once again I think alot of the documentation is going to be distro specific= to be newbie friendly but atleast a simple ip/brctl guide would help.
<= br>IMO knowing where to start and setting up networking were the biggest ba= rriers when I was picking up Xen a few years back.

I am also open to updating the blktap2 pages and README to reflect the = new tap-ctl userspace utilities and tips on driver development.

<= slightly off-topic but related>

With jailtime.org(stacklet) now charging for subscription there is nowhe= re to download pre-built clean Xen compatible images free of charge etc. I have pvgrub/pygrub capable images of Ubuntu/Debian/CentOS that I am consi= dering hosting for free.
Generally new users are confused on how to buil= d new paravirt VMs, I think prebuilt images are suboptimal but a good place= to start for beginners.

Joseph.

On 29 September 2011 00:00, I= an Campbell <Ian.Campbell@eu.citrix.com> wrote:
On Wed, 2011-09-28 at 14:48 +0100, Konrad Rzeszutek Wilk = wrote:
> On Wed, Sep 28, 2011 at 02:26:31PM +0100, Ian Jackson wrote:
> > Ian Campbell writes ("Re: [Xen-devel] Xen document day (Oct = 12 or 26)"):
> > > Since the guest APIs are stable there should be relatively l= ittle churn
> > > so perhaps a wiki page (or even series of pages) would be ap= propriate
> > > for this sort of thing?
> >
> > I want this to be in-tree. =A0If it's in-tree, we can refuse = patches
> > which do not update the documentation.
> >
> > > I think this would be good too and in fact even more importa= nt than the
> > > interface documentation. Everyone needs to be able to build = Xen to hack
> > > on it but only a subset need to know any particular API.
> > >
> > > Also although we recommend that users consume Xen via their = distro where
> > > possible such a guide would also help any who would rather b= uild from
> > > scratch (e.g. because we've asked them to "try the = latest version" or to
> > > bisect a bug etc).
> >
> > This would be a good candidate for a wiki page, backed up by revi= sions
> > of the in-tree README.
>
>
> Any recommendations on what would be a good format to write these &quo= t;interface"
> pages in?

For in-line (i.e. in xen/include/public/*.h) docs of APIs I played a<= br> little bit with integrating kernel-doc into the Xen build system but it
is tied a little too closely to the kernel build infrastructure.

Doxygen seems like a plausible alternative with life outside the kernel
etc. We actually appear to already have some doxygen stuff for the
pytyhon stuff (judging from the Makefile, I've not actually noticed the=
structured code comments anywhere)

For non-inline docs I think we decided that markdown would be a good
answer.

Ian.


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



--
<= b>
Founder | Director | VP Research
Orion Virtualisation Solutions=A0|=A0www.orionvm.com.au=A0| Phone= : 1300 56 99 52 | Mobile: 0428 754 846
--00151773e028c0e3b204ae12527d-- --===============0765242288== Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Content-Disposition: inline _______________________________________________ Xen-devel mailing list Xen-devel@lists.xensource.com http://lists.xensource.com/xen-devel --===============0765242288==--