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

[Lars Kurth <lars.kurth@xxxxxxx>]

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

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