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

[Joseph Glanville <joseph.glanville@xxxxxxxxxxxxxx>]

I think we should aim to get a meeting of interested parties happening on IRC before we action on a date or plan.
I just don't want to get started on something that will stall due to lack of direction.

<rant>

I am happy to contribute my time to do a significant amount of the work that bofh has requested but to do so effectively I really think we need somewhat of a clean start.
The current wiki contains too much content that just doesn't belong in the wiki, job postings, WIP status on projects that have long since died etc.
If we want to present the appearance that Xen is not a schizophrenic project and has clear direction, leadership and vision then we need actual documentation that reflects this.

I did get started on a full categorization of pages in the wiki but that quickly become something that is abit much to do in one session or alone for that matter.
It also highlighted some severe problems with how the current wiki is used - in my opinion atleast. It is my view that the official wiki should be reserved for highly relevant documentation.

I think we need to setup a guided rewrite/refactor of the core documentation so it resembles something close to this:

Overview (brief introduction, architecture, why xen is different and maybe abit of xen philosophy)
Getting started guide ( Installation of Xen on Debian - probably the simplest and easiest way to get started with Xen at the moment, start a Debian PV guest, start at Windows HVM guest)
Installation guide ( More indepth covering all the core distros and some more advanced installations including compilation from source and using the Linux 3.1 kernel, networking options etc)
Administration guide ( This bit requires atlot of discussion, do we recommend xm still? should we only support xl? If that is the case how to we recommend stuff like managed domains etc..)
Advanced topics.. stuff like Networking, PCI passthrough etc deserve their own pages

There also needs to be a developers section, preferably seperate entirely from the user documentation. If XCP could be sectioned off in some matter also that would be advantageous - basically to prevent confusion.
The current wiki is poluted with alot of architecture and design info that isn't of interest to a general user but is still key to understanding Xen from a developers point of view.

What the primary aim would be is to integrate as much best practices into these pages rather than having them spread around hundreds of wiki pages and even more mailing list posts.
To be honest I rarely look to the wiki if I want to know how to do something with Xen I am unfamilar with.. my first course of action is to search my archive of xen-devel/xen-users which isn't exactly a good thing.

The biggest issue with this sort of compaction is that Xen is fraught with choices.. there is just so many different ways of doing things.

I'm not trying to be critical of those that have spent many hours writing the current documentation, it is appreciated.
I just think we need a really concentrated effort around making the simple Xen tasks easier before expanding out to include the more complicated stuff.
Alot of us take for granted that we have been using Xen for a long time and many of these things come so naturally to us - whereas from the outside it all seems too difficult.

</rant>

That is what I am advocating anyways. First get direction, once we have that - we can build it. :)

Joseph.

On 20 October 2011 05:13, Lars Kurth <lars.kurth@xxxxxxx> wrote:

On 19/10/2011 09:38, Ian Campbell wrote:

It'll break links, but I guess that's a feature.

That's easy to fix: rename, check orphaned pages, fix those pages

How close are we to having the new wiki setup -- that would also solve this issue?

It wouldn't solve the issue really.

We could just manually add a header/banner ("attention box"?) to each archived page, that's no harder than renaming it I suspect. Ian.

That is true, but for a user it would still clutter the index

I am running behind publishing the blog post: will post it tomorrow

When do we want to start and end the session? That's the only outstanding question.

We also should take bofh's feedback seriously. The points he makes are exactly the ones I have identified to, but don't know enough yet to fix it.

Lars

--

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