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

On 22 October 2011 02:28, Lars Kurth <lars.kurth@xxxxxxx> wrote:

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

Aye, I didn't mean to say Xen was schizophrenic, infact I think it is precisely the opposite. My point was that the wiki and current documentation don't reflect this very wel.

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.

As I noted, this is just my opinion, its not my place to decide how people want to use it but if we could have to idea of what should and shouldn't be in there it makes it easy to then structure the information.

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?

Yes, maybe not -exactly- this format but something resembling it would be of value I think. Guiding people towards the beginners documentation and making it quite clear there is a reading progression will show much stronger cohesion.

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.

Fair enough, that would work well enough for this purpose.

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.

I have exactly the same problem, I just need to undertand what needs to be done and where.

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.

Precisely, documenting the more advanced features of Xen seems to be something that we can approach over time. Beginner documentation is immeadiately lacking and seems to be an easier target that would benefit more people.

Lars

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

WARNING - OLD ARCHIVES

xen-users

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