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

Maybe the wiki frontpage etc needs abit of a restructure to highlight the newer documentation and try steer people away from old stuff?
I am going to try do some tagging of the wiki pages tonight to mark what is out of date.
Many of the pages I think just need simplification.. the current wiki is somewhat of an information overload (which is fine but we shouldn't bombard new users if we can avoid it)

On 29 September 2011 21:01, Ian Campbell <Ian.Campbell@xxxxxxxxxxxxx> wrote:

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.

Yeah that's a tricky one, I guess we can start at wiki.xen.org and go from there.
Seeing as Debian repackages Xen, wiki.debian.org should probably be the final canonical location.

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

That is -much- better and as you said should be much easier to find..

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

I can think of some stuff to fill that up.
eg. Howto enable live migration, local VM storage guide possibly

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

WARNING - OLD ARCHIVES

xen-devel

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