Wiki focus - user versus developer documentation

Marko Knöbl openmoko.marko at gmail.com
Fri Sep 5 14:00:45 CEST 2008


2008/9/5 Ben Batt <benbatt at gmail.com>:
> Hi,
>
> Somebody wrote:
>>> ... there mostly is a clear difference between developing software and
>>> using the software. I can't imagine in which areas it would be hard to
>>> separate them. Can you tell me on which pages you think this could
>>> cause problems?
>
> As Michael Shiloh mentioned:
>
>> currently 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

I think those should be in the user category. I thought what you meant
by "developer documentation" was information on _developing_ software.
So information on how to develop a program or a patch / write a script
should be part of the developer documentation. Everything else should
be in the user documentation - for example applying patches, using
scripts, customizing scripts, changing configuration files.
If you meant something different by "developer documentation" I
misunderstood you.

> I think that as long as the purpose of a page is clear, these issues
> can be fixed as the software becomes more stable. If we know that a
> page is supposed to be part of the user manual, esoteric hacking
> commands to change the configuration can be deleted or moved to the
> developer page for that feature when they are no longer needed by
> normal users.

> On Fri, Sep 5, 2008 at 4:08 AM, Minh Ha Duong <haduong at centre-cired.fr> wrote:
>> The last time we discussed this, the conclusion was that we focus now on
>> categorizing, then we will do a mass page rename if needed. What I think was
>> more or less implicit was that we would take a few dozens of pages, tag them
>> as "Handbook", set a navigation template that look like a book's table of
>> content, and prefix everything with "Handbook/". Then we could
>> 1. Export them with tiddlywiki to be installed statically on every device.
>> 2. Export them statically every day/week/release to a different url,
>> maybe "Handbook.openmoko.org", with a noob-friendly CSS. With a searchbox and
>> a button that sends back to the wiki for editing of course.
>> 3. Use some Wiki-to-pdf tool to sell a nice handbook for Normal Users.
>>
>> Come to think of it, the handbook domain do not have to be managed by Openmoko
>> inc...
>> What do you guys say ?
>
> This sounds really good to me. I would suggest "Manual" instead of
> "Handbook", as it seems clearer, but maybe that's just me. I'm not
> sure I see a need for point 2, however - I think with good wiki layout
> and configuration this would probably be unnecessary, and it would be
> good to avoid things getting out of sync.
>

It's currently called "User's Manual" on the wiki, i think we should
keep that name.
I also agree that we don't necessarily need a different URL for the
manual, but we could make it optional, adding a line to the "User's
Manual" page saying "You may prefer to browse this manual with
tiddlywiki", which links to an appropriate page on tiddlywiki.



More information about the documentation mailing list