W3C home > Mailing lists > Public > public-webplatform@w3.org > October 2012

Feature centric documentation

From: Asbjørn Enge <asbjorn@hanafjedle.net>
Date: Mon, 15 Oct 2012 11:34:41 +0200
To: public-webplatform@w3.org
Message-ID: <AE376C5A80744939AFAADEB5D52AA897@hanafjedle.net>
Hi there, 

I think the structure of the documentation is getting good, but I think "getting to the docs" needs a different approach...

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

Who hits the documentation landing page (docs.webplatform.org/wiki) ??

* New users who are just browsing around
* Users who are interested in learning about web development
* Users who need to solve a problem but don't know how

To have a successful site the landing page needs to serve these people. I think they all should be considered important. I'll bet though, that a huge chunk on the landing page hits will be in the last group; users who need to solve a problem but don't necessarily know how and/or what technologies are available to them. Diggers.

So an important part of landing page should be to guide this type of users in the right direction; providing relevant starting points for diggers.

To do that we need to consider who most of these users are, and how think about their problem.

I guess it is safe to say that they have limited experience within the field of the problem. If not they would just search for "canvas drawImage" and fix their bug. Probably they have limited experience in web development as a whole.

If this is the case my guess is that they think about their problem in terms like "I need to rotate a photo", "I need to store some data", "I need to make my site faster", "I need to talk to a backend service". Things that will group multiple technologies and documentation categories. My guess is that they first want to see their options, and then dig into the concepts, objects and tutorials.

There are many ways to build such a structure, and mainly I'm hoping to spark a discussion about just that.

I'm not sure, but to me a "feature" type approach seems natural. Things like "storage", "network", "drawing", "3d", etc. are examples that could guide me in the right direction whenever I'm in a problem space I know little about. I see how that might be a HUGE list since these docs cover loads of features, but that just makes it "interesting" to work out a relevant structure :-P

What do you guys think?

// @asbjornenge
Received on Monday, 15 October 2012 10:35:03 UTC

This archive was generated by hypermail 2.3.1 : Wednesday, 8 May 2013 19:57:34 UTC