Wiki focus - user versus developer documentation

Michael Shiloh michael at openmoko.org
Fri Aug 29 08:36:36 CEST 2008



Ben Batt wrote:
> 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


Ben,

This seems like a great idea, and could indeed be an important reason 
for the many users having trouble finding what they are looking for on 
the wiki.

One fear: At this early stage, we have very little stable for users, so 
everything is developer oriented to some extent e.g. even solving a 
problem from a user's perspective might involve a patch or scripting, so 
it starts looking like it belongs in the developer category. What are 
your thoughts on this?

We might just have to make semi-arbitrary classifications on some pages, 
and as time goes on we would expect some pages that had been in the 
developer category to either become unnecessary or to be migrated to the 
user category.

I like the idea very much, and I like the way the Blender wiki is 
divided. I'd like to see what other people say, but my gut feeling is 
that you've identified one fundamental source of confusion.

Thanks!

Michael



More information about the documentation mailing list