On 22/10/2011 00:33, Joseph Glanville wrote: > 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. I think we have two choices: a) We re-write large sections of the wiki with the purpose of making it more accessible b) We use create methods to highlight existing stuff and focus on filling gaps, etc. I think that b) is more valuable. Here are a few ideas: Trails: I have come across the idea of wiki trails before. These are pages/indexes which lead the reader through a series of articles. The key is that these are easily identified and highlighted from the main page. E.g. we could use Trails (listing all trails and a page template), Trails/XenOverview, Trails/XenGettingStarted, etc. By doing this, we group the existing documents, rather than re-writing a lot of stuff and just refactoring it. This would make an easier start, and if somebody wishes they can always clean up and refactor the documentation which makes up a trail. I had a look around for MoinMoin plug-ins for something which may help with trails: not much, but there are a couple of plugins that may help Being able to create TOCs across sevaleraL wiki pages (http://moinmo.in/SteveTindle/DocTools from http://moinmo.in/MacroMarket#Release_1.5 using /EnhancedTableOfContents /SetSection /TocOf ) > 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. I hope I will get some of this out of Wed. > 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. Let's see whether we can get enough structure in place on Wed and make a good start Lars