Re: Feature centric documentation

Disclaimer: I am, myself, a newbie when it comes to wikis.  I rarely browse them (wikipedia when I have a specific topic, usually through google searches, and other community wikis [think Halopedia, etc] on occasion, again through google searches), and even more rarely edit them.

As a newbie, though, I'm thinking my "experience" with them is particularly relevant.  No to sound arrogant or anything (y'all will keep me humble, right?).

> * Searching is only good if you know what you are looking for.
> * Digging needs a relevant structure to work.

+1 on both of these.

My experience with mediawiki's search is that it's difficult to use/understand at best, and completely useless at worst.  There's a relevant question in the forum[1] which says:

> Say for example I want information on the table HTML element, so I do
> a search for "table":
> http://docs.webplatform.org/w/index.php?search=table&fulltext=+&title=Special%3ASearch
>
> The first 8 of 14 title results on that page are [duplicates], and
> the page html/elements/table doesn't appear in the title results list
> at all.

I don't know if this is inherent to medawiki's search, or if it's just a case of bad tuning.  Either way, as it stands it has very limited usefulness.

As for digging, I've always thought wikis were very low-discoverability -- that is, it's difficult, if not impossible, to simply explore (randomly, without a specific topic) a wiki's content.  Relevant intra-article links are explicit and manual (for the most part -- I understand there's some automatic linkage where CamelCase words are concerned?), so a) existing links may not be relevant, and b) relevant links may not yet have been made.  I read somewhere that someone had mentioned using a sitemap plugin (which I'm probably +1 for), but again, that's something that has to be explicitly setup, so your average wiki probably doesn't have it.  Essentially, you have to know what you're looking for to make good use of a wiki.

> I'm not sure, but to me a "feature" type approach seems natural.

I think a featuremap is a great idea, though I'm not sure it should go on the front page.  Perhaps briefly summarized (or sampled) and linked to from there.  The front page, as it stands, is a "general overview" of the wiki, its purpose, how to contribute, and a starting point for finding some potentially relevant content (the "Explore our web dev docs" section), and I think that's probably a good "first impression".

So +1 for a featuremap page, but with its presence on the homepage being similar to the "Explore" table, with maybe the 6-8 most popular / widely used/discussed* topics listed and a link to the featuremap page from there.


Andrew / eternicode


[1] http://talk.webplatform.org/forums/index.php/2063/can-search-accuracy-be-improved

* There's a topic for discussion!  Criteria for "popular".

Received on Monday, 15 October 2012 14:16:48 UTC