Re: [Xen-API] [Xen-devel] Proposals/changes for a new Wiki Front-Page - need input/mods/creative proposals

[Rolu <rolu@xxxxxxxx>]

On Thu, Jun 7, 2012 at 3:14 PM, George Dunlap
<George.Dunlap@xxxxxxxxxxxxx> wrote:
> Sorry to throw in a criticism without a constructive solution, but I
> just want to register one opinion: To me clicking on a link and seeing
> a "Category" page says very strongly, "I couldn't be bothered to
> actually do any work here; I'll leave you to do all the work to figure
> out what page you need."  When I encounter a Category page on my walk
> through the Xen wiki, I don't even look, but immediately turn to
> Google.  I think a page which is has some kind of logical flow to it
> but perhaps a little out-dated is much better than a page which just
> tosses up a bunch of titles in no order and lets you figure it out.
>

I do agree with this, generally. Browsing a wiki and hovering over a
link and seeing that it goes to a Category: page is... somehow
disappointing. Most of the time you won't get any help finding what
you need there so people may already be conditioned to just ignore
them.

> I think in an ideal world, we'd have people who were "maintainers" of
> the wiki just like there are maintainers of different subsections of
> the codebase.  Until that time, could we maybe draw up a set of
> "tests" to run on the docs, which can be assigned to people on DocDay?
>  One simple thing could be, "Make sure X page is up-to-date" (which
> may include, "Look at the Category: page and make sure everything
> there is listed somewhere on the manually-generated page"); another
> could be a scenario, "Pretend you're a [foo] and you want to know
> [bar].  Start at the top level page and make sure you can find all the
> information you need."  If each "test" was something any motivated
> developer/community member could do, and only took 5-10 minutes, it
> should be pretty sustainable.  What do you think?
>

I think that's a really good idea. Unit tests for the documentation? ;-)

Related to the discussion: I had a go at a unified books & manuals
page: http://wiki.xen.org/wiki/User:Rolu/Books_and_Manuals

Books and manuals are, I think, the only documents that can't really
be linked by topic (beyond something general such as "xcp") as they
are generally quite large, so a page like this makes most sense. Let
me know what you think.

_______________________________________________
Xen-api mailing list
Xen-api@xxxxxxxxxxxxx
http://lists.xen.org/cgi-bin/mailman/listinfo/xen-api