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

[Lars Kurth <lars.kurth@xen.org>]

On 21/10/2011 04:44, Joseph Glanville wrote:
> 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 hang out with a few the day before the docs day and 
coordinate a bit
I think there is a lot we can do though

> 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.
Agreed that some stuff should just be deleted. The key issues is that 
the wiki today has a flat structure.
I am happy to delete stuff like job postings, old minutes, WIP status 
and truly dead stuff and archive plain old stuff (which may still be of 
value to some people.

I think its unfair to say Xen is a schizophrenic project. The issue has 
been that the Wiki has not been managed ever and MoinMoin is inherently 
unmanageable

> 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.
Agreed and categories don't work well with MoinMoin

> 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 would agree with you, if we were in a perfect world. But we have 
baggage, so to some degree this discussion is moot. I also think that 
this question is handled quite differently by different projects.

> 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
Are you suggesting we restructure the wiki front-page around this?

> 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.
We do not have that many XCP pages. MoinMoin sucks at sectioning stuff 
off. The only thing which could sort of work is to use 
<namespace>/<pagename> ... we could have XCP/<pagename> and so on. If 
categories worked properly, they could be used too.

> 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.
Part of the issue is that it is hard for me to identify what is what. If 
I had a good approximation of what is what, I (or others) could just go 
through the motions and re-encode stuff accordingly.

> 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>
I think what you seem to be saying is that there would be extremely high 
value in having a "Getting started" guide and some other entry level 
documentation (even if just an index page) accessible from the wiki 
front page.

Lars