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
Home