Wiki focus - user versus developer documentation

Ben Batt benbatt at gmail.com
Fri Aug 29 08:19:47 CEST 2008


Hi all,

This is something that has been floating around in my mind for a bit,
but was crystallised when I saw this message from Michael Shiloh a few
days ago:

On Tue, Aug 26, 2008 at 7:36 AM, Michael Shiloh <michael at openmoko.org> wrote:
> While searching for the list of /sys files I stumbled onto
> http://wiki.openmoko.org/wiki/List_of_technical_documentations,
>
<snip>
>
> ...looking over the list of links, it strikes me that pretty much
> everything on the wiki is in fact technical documentation. True, there
> are clear exceptions, but does it really make sense to have a page that
> is essentially the same as the index?
>

It seems to me that this is one of the major problems with the wiki at
the moment: there is no clear separation between user documentation
(e.g. manuals) and developer documentation (e.g. build instructions).
This means that as a user, it is very hard to find out how to get
things working without wading through a whole heap of developer
documentation. I realise that most users of the phone will also be
developers (I plan to do some hacking on my Freerunner), but even
then, there are many times when you just want to find out how a
particular program is supposed to work.

An example: When I got my Freerunner a few weeks ago, I went to
http://wiki.openmoko.org/wiki/Getting_Started_with_your_Neo_FreeRunner
and followed the instructions to set it up. So far, so good.

I then wanted to find out how to use the Today screen, so I followed
the "Default Software" link in the little quick link box (which looks
far too much like a table of contents), and got
http://wiki.openmoko.org/wiki/Om_2007.2 . This has a brief paragraph
on installing OM 2007.2, followed by a large chunk of complicated
build instructions, which was not what I was after.

I then followed the "Today" link in the quick link box. This links to
http://wiki.openmoko.org/wiki/Today/2007.2 , which looks like a UI
design document - there are a bunch of use cases, a list of planned
functionality, etc. There are some configuration and usage
instructions, but a lot of them are hidden inside design
documentation. Overall, it was quite hard to find out what I could and
couldn't do with the Today screen. Which bits are implemented? Which
are only proposed?

I realise that 2007.2 has now been succeeded by 2008.8, which seems to
have better user-focused documentation. This is a good thing, but I
think it would be useful to have a consensus among the wiki
maintainers on how to manage the separation between user and developer
documentation. I think the Blender wiki
(http://wiki.blender.org/index.php/Main_Page) manages this fairly
well. Perhaps some inspiration could be drawn from
http://wiki.blender.org/index.php/Meta/Blender_Wiki ?

Ben



More information about the documentation mailing list