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

[Ian Campbell <Ian.Campbell@xxxxxxxxxxxxx>]

On Thu, 2011-09-29 at 12:24 +0100, Joseph Glanville wrote:
> 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)

I think Lars (now CC'd) is planning a switch to a new wiki platform
since the current one is very long in the tooth and not especially
capable. AIUI part of the transfer will involve discarding out of date
stuff and better categorisation of correct/up-to-date pages etc.

I'm not sure how the timescales for that transition compare with this
documentathon though...

Ian.

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