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

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

[-- Attachment #1.1: Type: text/plain, Size: 4096 bytes --]

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 
<http://moinmo.in/MacroMarket/EnhancedTableOfContents> /SetSection 
<http://moinmo.in/MacroMarket/SetSection> /TocOf 
<http://moinmo.in/MacroMarket/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


[-- Attachment #1.2: Type: text/html, Size: 6571 bytes --]

[-- Attachment #2: Type: text/plain, Size: 138 bytes --]

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