From mboxrd@z Thu Jan 1 00:00:00 1970 From: Lars Kurth Subject: Re: [Xen-users] Re: Xen document day (Oct 12 or 26) Date: Fri, 21 Oct 2011 16:28:45 +0100 Message-ID: <4EA18FAD.7080102@xen.org> References: <4E92D809.9000504@xen.org> <20111010160404.GB28646@phenom.oracle.com> <4E946EB9.7050209@xen.org> <20111013180244.GC15499@phenom.oracle.com> <5400260811821008556@unknownmsgid> <1318859996.16132.16.camel@zakaz.uk.xensource.com> <4E9C4516.2070902@xen.org> <1318864667.16132.22.camel@zakaz.uk.xensource.com> <4E9C4BAB.9020605@xen.org> <20111018132618.GA19611@phenom.dumpdata.com> <1319013528.3385.59.camel@zakaz.uk.xensource.com> <4E9F1361.5020906@xen.org> Mime-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1; format=flowed Content-Transfer-Encoding: 7bit Return-path: In-Reply-To: List-Unsubscribe: , List-Post: List-Help: List-Subscribe: , Sender: xen-devel-bounces@lists.xensource.com Errors-To: xen-devel-bounces@lists.xensource.com To: Joseph Glanville Cc: Andrew Bobulsky , "xen-users@lists.xensource.com" , "xen-devel@lists.xensource.com" , Ian Campbell , Konrad Rzeszutek Wilk List-Id: xen-devel@lists.xenproject.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. > > 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 / ... we could have XCP/ 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. > > 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