From: Christi Alice Scarborough <christi_at_chiark.greenend.org.uk>
Date: Sat, 19 Jun 2004 15:00:33 +0100

Björn Stenberg wrote:

>> Is this intended to replace or to complement the manual?
>
>
>
> I think there will always be a desire for a PDF manual that you can
read off-line and print.
>
> My vision of the wiki in this context is that we write the manual in
wiki and then produce a pdf version from that material. This means the
manual can constantly be corrected and refined without having to bounce
staroffice files back and forth between people.


I don't want to be difficult, but I see a few problems with that approach.

(1) Consistency - in general for a user manual you need an editor to
give the thing a unified look and feel, otherwise it's confusing for users.

(2) Format differences - a paper/PDF manual needs to be formatted
differently from a hypertext one. There is in some sense an order in
which things should come with a paper manual. Start simple and then get
more complex. This is actually something the 2.2 manual is very bad at,
since it deals with topics beyond the grasp of many users before it
1explains the user interface.

(3) Format conversion. HTML -> PDF is likely to end up producing a file
that's difficult to read and unprofessional looking. One of the things
that the current manual gets right is the fact that it does look polished.

These problems aren't insurmountable, I'm sure, but it seems as though
you're hoping a coherent manual will spontaneously evolve. I'd have to
say that the chances of that happening are slim. If nothing else, there
  needs to be some sort of plan to put the contents of the current
manual into the wiki.

I've been busy the past couple of weeks, and haven't had time to get
seriously into updating the manual. Given this development, maybe
that's for the best. I'll happily work within whatever structure the
core team wants, but I don't see how you propose to create a manual from
a wiki. I've seen quite a few wiki documented projects (like NoCat)
which are very difficult to fathom because there's no overarching
structure to the docs, and one ends up clicking through page after page
hoping to find the info you're looking for.

Perhaps I'm misunderstanding what you're trying to do though. I'll hold
off from further work on the manual until it's clearer to me exactly
what's wanted from the OpenOffice and wiki manuals, because I don't want
to be spending time on things that aren't wanted or needed.

Christi


_______________________________________________
http://cool.haxx.se/mailman/listinfo/rockbox
Received on 2004-06-19