Re: [Xen-devel] Xen document day (Oct 12 or 26)

[Joseph Glanville <joseph.glanville@xxxxxxxxxxxxxx>]

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

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

Joseph.

On 29 September 2011 00:00, Ian Campbell <Ian.Campbell@xxxxxxxxxxxxx> 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@xxxxxxxxxxxxxxxxxxx
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

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