Rolu
2012-Jun-07 14:45 UTC
Re: [Xen-devel] Proposals/changes for a new Wiki Front-Page - need input/mods/creative proposals
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.