Xen devel - Jun 2012 - Proposals/changes for a new Wiki Front-Page - need input/mods/creative proposals

Hi everybody,

at the last Xen Docs Day I got feedback that it is too hard to find 
useful information from the wiki front page. Also, much of the 
information on the front page (the list of categories) is actually 
duplicated on the wiki navigation bar.

There were a few items of feedback I received:
1) The front page should be more use-case driven and be aimed at 
beginners and users
2) Wiki Search is broken.
- Actually it is not, the UI design of search in MediaWiki is bad.
- Typing "Foo"+return into the search box will actually perform
Go(Foo)
which searches for "Foo" in titles only
- To search you need to type "Foo" and press search
3) Google search is broken.
- Some redirects are still needed but mostly we have fixed this now.
- The ones we know of are: (e.g. wiki.*xen*source.com is still hanging 
around)
- If you find SEO issues: let us know at http://wiki.xen.org/wiki/SEO_Issues

To facilitate the discussion on the new front-page, I created a proposal 
space for everybody to play with and make proposals
- http://wiki.xen.org/wiki/Proposals/ : list of proposals
- http://wiki.xen.org/wiki/Proposals/Main_Page1 : a more use-case 
focussed front-page
- http://wiki.xen.org/wiki/Talk:Proposals/Main_Page1 : discussion page, 
feel free to add
- http://wiki.xen.org/wiki/Proposals/Main_Page2 : a copy of the previous 
page, feel free to change
- http://wiki.xen.org/wiki/Talk:Proposals/Main_Page2 : discussion page, 
feel free to add

Feel free to add new proposals

Best Regards
Lars


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

Lars Kurth writes ("[Xen-devel] Proposals/changes for a new Wiki Front-Page
- need input/mods/creative proposals"):
> - http://wiki.xen.org/wiki/Proposals/Main_Page1 : a more use-case focussed
> front-page
This one is already much better than the existing front page.  I have
made some more changes.

The links under "Xen Docs" are rather poor.  I don''t know
what pages
we have that would do better, but the top link being the Wiki category
listing is quite unhelpful.

Ian.

On 01/06/2012 18:54, Ian Jackson wrote:
> Lars Kurth writes ("[Xen-devel] Proposals/changes for a new Wiki
Front-Page - need input/mods/creative proposals"):
>> - http://wiki.xen.org/wiki/Proposals/Main_Page1 : a more use-case
focussed
>> front-page
> This one is already much better than the existing front page.  I have
> made some more changes.
Great!
> The links under "Xen Docs" are rather poor.  I don''t
know what pages
> we have that would do better, but the top link being the Wiki category
> listing is quite unhelpful.
Would a ...
1) link to http://wiki.xen.org/wiki/Xen_4.x_Manuals instead of 
http://wiki.xen.org/wiki/Category:Manual be better?
2) We could move http://wiki.xen.org/wiki/Xen_Beginners_Guide one up - 
it is a step-by-step tutorial to set up Xen 4 with Squeeze

Part of the problem is that there is a lot of stuff and it is hard to 
choose what is relevant

On Wed, Jun 6, 2012 at 5:35 PM, Lars Kurth <lars.kurth@xen.org>
wrote:
> On 01/06/2012 18:54, Ian Jackson wrote:
>>
>> Lars Kurth writes ("[Xen-devel] Proposals/changes for a new Wiki
>> Front-Page - need input/mods/creative proposals"):
>>>
>>> - http://wiki.xen.org/wiki/Proposals/Main_Page1 : a more use-case
>>> focussed
>>> front-page
>>
>> This one is already much better than the existing front page.  I have
>> made some more changes.
>
> Great!
>
I agree it''s much better. Since the main categories are "help with
xen" and "help with xcp" it would be nice if there were a few
lines at
the top of the page explaining which is which, so (new) people can
have a better idea of where to look. The descriptions from
http://xen.org/products/ and a link to
http://wiki.xen.org/wiki/Xen_/_XCP_/_XCP_on_Linux_Overview would work.
The latter is already linked in the "getting started with xen" column
but would be better off at the top since it gives a feature table of
both.
>> The links under "Xen Docs" are rather poor.  I don''t
know what pages
>> we have that would do better, but the top link being the Wiki category
>> listing is quite unhelpful.
>
> Would a ...
> 1) link to http://wiki.xen.org/wiki/Xen_4.x_Manuals instead of
> http://wiki.xen.org/wiki/Category:Manual be better?
> 2) We could move http://wiki.xen.org/wiki/Xen_Beginners_Guide one up - it
is
> a step-by-step tutorial to set up Xen 4 with Squeeze
>
> Part of the problem is that there is a lot of stuff and it is hard to
choose
> what is relevant
>
As someone who started with Xen not long ago, I much prefer dedicated
link pages over Category: pages. The latter just give a big unsorted
(alphabetical doesn''t count, needs to be sorted by subtopic to be a
useful sort) list of pages of widely varying scope and usefulness.
It''s better than nothing, sure, but a page that sorts them by topic or
purpose or something (much like this proposed front page really) is a
lot better.

Rolu,

thanks for the feedback.


xen" and "help with xcp" it would be nice if there were a few
lines at
> the top of the page explaining which is which, so (new) people can
> have a better idea of where to look.

So you mean a link to Xen and XCP from the headline, or a tagline
describing what Xen/XCP is? Two lines are probably OK; more would probably
break up the navigation too much.

> The descriptions from
> http://xen.org/products/ and a link to
> http://wiki.xen.org/wiki/Xen_/_XCP_/_XCP_on_Linux_Overview would work.
> The latter is already linked in the "getting started with xen"
column
> but would be better off at the top since it gives a feature table of
> both.
>
I am wondering whether Xen Features / XCP Features in one of the boxes
would not be better.

> As someone who started with Xen not long ago, I much prefer dedicated
> link pages over Category: pages. The latter just give a big unsorted
> (alphabetical doesn''t count, needs to be sorted by subtopic to be
a
> useful sort) list of pages of widely varying scope and usefulness.
> It''s better than nothing, sure, but a page that sorts them by
topic or
> purpose or something (much like this proposed front page really) is a
> lot better.
>
How about a compromise? Category pages have two parts:
1) A fixed part that can be used for any content, such as lists of
important articles by topic or other ciriteria
    An example of this is
http://wiki.xen.org/wiki/Category:Host_Install(and some of the pages
linked from it)
2) The auto-generated index

I know that some people are don''t like category pages. However, until
somebody steps up and provides an alternative, which to do well requires
a) Classifying articles
b) Grouping them by topic or purpose
c) Encoding that grouping in some manual index
d) Keeping these up-to-date

... the category pages are all we have and are a lot better than what we
had in the old wiki. And they are self-maintaining.

The fact that we are having this discussion is actually good. I am open to
suggestions and maybe we just need a small number of manually maintained
indexes (or categories with maintained content at the top). Maybe to make
this really work and get better navigability we need some degree of
ownership in the wiki: i.e. community members owning content, categories,
etc. and being responsible for classifying, grouping and making it more
accessible.

I also started experimenting with shortcut boxes on pages such as
http://wiki.xen.org/wiki/Xen_Overview &
http://wiki.xen.org/wiki/Getting_Started and wanted to know what people
thought of these and whether these improve navigability.

Lars


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

On Thu, Jun 7, 2012 at 11:24 AM, Lars Kurth <lars.kurth.xen@gmail.com>
wrote:
> Rolu,
>
> thanks for the feedback.
>
>
>> xen" and "help with xcp" it would be nice if there were
a few lines at
>> the top of the page explaining which is which, so (new) people can
>> have a better idea of where to look.
>
>
> So you mean a link to Xen and XCP from the headline, or a tagline
describing
> what Xen/XCP is? Two lines are probably OK; more would probably break up
the
> navigation too much.
>
Yeah, a tagline, as a disambiguation between Xen and XCP. I combined a
few sentences from the various pages and got this:

--
Xen is an open-source type-1 or baremetal hypervisor, which makes it
possible to run many instances of an operating system or indeed
different operating systems in parallel on a single machine (or host).
The Xen Cloud Platform (XCP) is an open source enterprise-ready server
virtualization and cloud computing platform with Xen at the core. XCP
can be thought of as the open source release of the commercial Citrix
XenServer.
See here for a [feature matrix]
--
>>
>> The descriptions from
>> http://xen.org/products/ and a link to
>> http://wiki.xen.org/wiki/Xen_/_XCP_/_XCP_on_Linux_Overview would work.
>> The latter is already linked in the "getting started with
xen" column
>> but would be better off at the top since it gives a feature table of
>> both.
>
> I am wondering whether Xen Features / XCP Features in one of the boxes
would
> not be better.
>
That''d probably work too yes, and might look nicer to boot.
>>
>> As someone who started with Xen not long ago, I much prefer dedicated
>> link pages over Category: pages. The latter just give a big unsorted
>> (alphabetical doesn''t count, needs to be sorted by subtopic to
be a
>> useful sort) list of pages of widely varying scope and usefulness.
>> It''s better than nothing, sure, but a page that sorts them by
topic or
>> purpose or something (much like this proposed front page really) is a
>> lot better.
>
> How about a compromise? Category pages have two parts:
> 1) A fixed part that can be used for any content, such as lists of
important
> articles by topic or other ciriteria
>     An example of this is http://wiki.xen.org/wiki/Category:Host_Install
> (and some of the pages linked from it)
> 2) The auto-generated index
>
That does certainly help. That way a manual list can be built while
keeping the category page, and it could replace it once it proves to
be good enough.
> I know that some people are don''t like category pages. However,
until
> somebody steps up and provides an alternative, which to do well requires
> a) Classifying articles
> b) Grouping them by topic or purpose
> c) Encoding that grouping in some manual index
> d) Keeping these up-to-date
>
> ... the category pages are all we have and are a lot better than what we
had
> in the old wiki. And they are self-maintaining.
>
Especially d is an issue I think. Self maintenance is an attractive feature.
> The fact that we are having this discussion is actually good. I am open to
> suggestions and maybe we just need a small number of manually maintained
> indexes (or categories with maintained content at the top). Maybe to make
> this really work and get better navigability we need some degree of
> ownership in the wiki: i.e. community members owning content, categories,
> etc. and being responsible for classifying, grouping and making it more
> accessible.
>
I think the most important step would be to flesh out the high level
structure of the wiki a bit more. If that is done well, pages can be
put in their place much easier. The new front page starts this (xen
versus xcp, then the boxes) but the level below that is rather messy.
For example, there are howtos, FAQs, Q&As, books, guides, tutorials,
examples, overviews, and so on, with lots of overlap. These categories
are all about how the information is presented and that might be the
wrong approach. When I come to the wiki I''ll have questions like
"I
want to know more about how to handle disk storage" or "I want to know
how to install operating system XYZ in a domU" or "I want to know how
to switch toolstacks". I don''t care if that info is found in a
howto,
FAQ, book, guide, tutorial or example though, as long as I find it.
So, setting up and using categories that tell you what information is
there would help.
> I also started experimenting with shortcut boxes on pages such as
> http://wiki.xen.org/wiki/Xen_Overview &
> http://wiki.xen.org/wiki/Getting_Started and wanted to know what people
> thought of these and whether these improve navigability.
>
Yes, that helps. They would also make a good link page or category
though. For example, the box on the getting started page could be
titled "beginner documentation" or something.

On Thu, Jun 7, 2012 at 10:24 AM, Lars Kurth <lars.kurth.xen@gmail.com>
wrote:
> Rolu,
>
> thanks for the feedback.
>
>
>> xen" and "help with xcp" it would be nice if there were
a few lines at
>> the top of the page explaining which is which, so (new) people can
>> have a better idea of where to look.
>
>
> So you mean a link to Xen and XCP from the headline, or a tagline
describing
> what Xen/XCP is? Two lines are probably OK; more would probably break up
the
> navigation too much.
>
>>
>> The descriptions from
>> http://xen.org/products/ and a link to
>> http://wiki.xen.org/wiki/Xen_/_XCP_/_XCP_on_Linux_Overview would work.
>> The latter is already linked in the "getting started with
xen" column
>> but would be better off at the top since it gives a feature table of
>> both.
>
> I am wondering whether Xen Features / XCP Features in one of the boxes
would
> not be better.
>
>>
>> As someone who started with Xen not long ago, I much prefer dedicated
>> link pages over Category: pages. The latter just give a big unsorted
>> (alphabetical doesn''t count, needs to be sorted by subtopic to
be a
>> useful sort) list of pages of widely varying scope and usefulness.
>> It''s better than nothing, sure, but a page that sorts them by
topic or
>> purpose or something (much like this proposed front page really) is a
>> lot better.
>
> How about a compromise? Category pages have two parts:
> 1) A fixed part that can be used for any content, such as lists of
important
> articles by topic or other ciriteria
>     An example of this is http://wiki.xen.org/wiki/Category:Host_Install
> (and some of the pages linked from it)
> 2) The auto-generated index
>
> I know that some people are don''t like category pages. However,
until
> somebody steps up and provides an alternative, which to do well requires
> a) Classifying articles
> b) Grouping them by topic or purpose
> c) Encoding that grouping in some manual index
> d) Keeping these up-to-date
>
> ... the category pages are all we have and are a lot better than what we
had
> in the old wiki. And they are self-maintaining.
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 can certainly see that there were "liveness" problems with summary
pages; but I don''t think that the Categories pages, as we have now,
really help that much.
> The fact that we are having this discussion is actually good. I am open to
> suggestions and maybe we just need a small number of manually maintained
> indexes (or categories with maintained content at the top). Maybe to make
> this really work and get better navigability we need some degree of
> ownership in the wiki: i.e. community members owning content, categories,
> etc. and being responsible for classifying, grouping and making it more
> accessible.
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?

One thing that might make the Category: page more useful is if we
could include "index tags" on articles, and then sort the Category:
pages by those tags instead of by title.  But I''m not sure how easy
that is to do with the current wiki.

 -George

On Thu, Jun 7, 2012 at 3:14 PM, George Dunlap
<George.Dunlap@eu.citrix.com> 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.

On 07/06/2012 14:14, George Dunlap 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." 
One question: do you feel this for any category page, or just "empty" 
category pages? For example, if the content listed in 
http://wiki.xen.org/wiki/User:Rolu/Books_and_Manuals was actually the 
first thing you saw when going to 
http://wiki.xen.org/wiki/Category:Manual would you still feel that way?
> 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. 
There is no reason why a category page cannot have a logical flow at the 
top and just the list of articles at the bottom.
> I can certainly see that there were "liveness" problems with
summary
> pages; but I don''t think that the Categories pages, as we have
now,
> really help that much. 
Right now they are just indexes. The advantage of using category pages 
with content at the top is that it is relatively easy to make sure that 
every article in the category is in some kind of logical group.
> 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?
Again, that would be almost a case in point for having some better 
manually created index at the top of a category page.
If there was an easy way of finding out what is new in a category index 
(I am not sure it is), then creating such tests would be relatively easy.

However to be honest, there were already "easy" items like this since 
the beginning of docs days, which have been on the TODO list since day 
1. E.g.
* http://wiki.xen.org/wiki/Category:Contains_Needs_Formatting
* http://wiki.xen.org/wiki/Category:Contains_TODO
* http://wiki.xen.org/wiki/Category:Contains_Needs_Action

But apart from me, nobody really cares. So having some tests won''t
work,
unless people will execute them. And I don''t have much hope for that.
> One thing that might make the Category: page more useful is if we
> could include "index tags" on articles, and then sort the
Category:
> pages by those tags instead of by title.  But I''m not sure how
easy
> that is to do with the current wiki.
I am not quite sure what you mean. There are actually a few extensions 
which may deliver what you need, but of course we likely wont be able to 
install these as these dont come as Debian packages.

With those type of plug-ins it would be possible to create indexes 
using  criteria such as:
  - List Xen Tutorials (i.e. articles in Xen and Tutorials)
  - List Xen Tutorials for Debian
  - List XCP FAQs for Debian that have been edited recently
  - Etc.

Examples of such extensions are:

  * Semantic MediaWiki <http://semantic-mediawiki.org>
      o
<http://semantic-mediawiki.org/wiki/Help:Introduction_to_Semantic_MediaWiki#Where_SMW_can_help>allows
        further intersection with sets of pages defined in terms of
        relations and attributes
      o <http://semantic-mediawiki.org/wiki/Help:Inline_queries>provides
        relation- and attribute-related info about the selected pages
        and in-page display on any page of categories the same or
        another page is in

  * DynamicPageList
   
<http://www.mediawiki.org/wiki/Extension:DynamicPageList_%28third-party%29>
    (ext) or DynamicPageList
   
<http://www.mediawiki.org/wiki/Extension:DynamicPageList_%28Wikimedia%29>
    (MW) extension can be used to:
      o intersection of categories
      o generate a list of all those articles (or a random sample)
      o show metadata of the articles (popularity, date of last update, ..)
      o show one or more chapters of the articles
(''transclude'' content)
      o show parameter values which are passed to the common template
      o order articles appropriately
      o present the result in a sortable table (e.g.)
      o use multi column output

  * Forum <http://peize.wikia.com/wiki/Help:Forum>
      o intersection of categories and complements of categories
      o provides the time of last edit for each page





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