Wiki focus - user versus developer documentation
openmoko.marko at gmail.com
Fri Sep 5 14:00:45 CEST 2008
2008/9/5 Ben Batt <benbatt at gmail.com>:
> 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
> 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
>> 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