Re: Xen document day (Oct 12 or 26)

From: Ian Campbell <Ian.Campbell@eu.citrix.com>
To: Joseph Glanville <joseph.glanville@orionvm.com.au>
Cc: Daniel Castro <evil.dani@gmail.com>,
	"xen-devel@lists.xensource.com" <xen-devel@lists.xensource.com>,
	Ian Jackson <Ian.Jackson@eu.citrix.com>,
	Konrad Rzeszutek Wilk <konrad.wilk@oracle.com>
Subject: Re: Xen document day (Oct 12 or 26)
Date: Thu, 29 Sep 2011 12:01:44 +0100	[thread overview]
Message-ID: <1317294104.26672.155.camel@zakaz.uk.xensource.com> (raw)
In-Reply-To: <CAOzFzEhnr7Ri42V1AUMLw-xRn+9NQwu8Pkq8iPc=pS12w=Vnog@mail.gmail.com>

On Thu, 2011-09-29 at 11:53 +0100, Joseph Glanville wrote:
> +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.

Excellent, it looks like it needs it...

> Making it simple for people to get started with Xen on a distro they
> are comfortable with is a good step forward.

Agreed. In fact for many users this is probably the end goal, not just a
step along the way.

> I know distro specific guides could turn into a nightmare but I am
> open to writing one for Debian 6 Squeeze,

In cases such as this we should also consider updating the distro's wiki
page. I'm not sure where the canonical guide should live (wiki.xen.org
or wiki.debian.org) but they should certainly cross reference each
other.

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

We now have
http://wiki.xensource.com/xenwiki/HostConfiguration/Networking which
could do with being made more discoverable.

There is also http://wiki.xensource.com/xenwiki/HostConfiguration but
its looking pretty sad right now...

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

There was discussion of Debian providing such a thing on debian-deval
back in late July, I should chase that up really.

Cheers,
Ian.

> 
> Joseph.
> 
> On 29 September 2011 00:00, Ian 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 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