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

[Joseph Glanville <joseph.glanville@orionvm.com.au>]

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

Agreed on all counts.

I think you have a very good point in the "trails" concept... the idea of
having an information graph resounds with the goal to make advanced
documentation accessible but not overwhelm newcomers.

The DocTools macros look good.

Joseph.



On 24 October 2011 22:35, Lars Kurth <lars.kurth@xen.org> wrote:

>  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
>
>


-- 
*
Founder | Director | VP Research
Orion Virtualisation Solutions* | www.orionvm.com.au | Phone: 1300 56 99 52
| Mobile: 0428 754 846

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

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

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