[haiku-doc] Re: End user documentation
- From: "Niels Reedijk" <niels.reedijk@xxxxxxxxx>
- To: haiku-doc@xxxxxxxxxxxxx
- Date: Sun, 17 Aug 2008 12:44:59 +0200
Hi gang,
First of all, thanks Scott, for attempting the first bit of end user
documentation. As I have been working on developer documentation, and
hope to do so again in a short while, I sort of left user
documentation where it was. Now, I do not want to hinder anyone in
starting this process, I will even try to put some energy into getting
a documentation wiki, if that's where things end up. I do want to drop
some thoughts in the discussion before I do, though.
First of all, I'm still in doubt what the best way to start this
process is. I believe that documentation has to be structured, else it
will be a big collection of thoughts that end up nowhere. So a certain
amount of central planning has to go into how the documentation should
be done. This means thinking about the target groups, the range of the
docs (IMO, not everything should be documented, you don't want to end
up becoming boring), the style and the format. At the other hand, when
I started documenting the API, I didn't have the right idea right away
anyway. I just started with some things, drew up some lessons from
that, wrote the guidelines and then continued in that vain.
So my suggestion would be that a few interested individuals work
together for a while, to try out some things, draft up some standards
and then open up for business for the main public.
Secondly, my thoughts were on the form and style of the documentation.
I have some experience with the KDE documentation (as a translator,
not as a writer or user). See the user guide:
http://docs.kde.org/stable/en/kdebase-runtime/userguide/index.html. I
think that document is clumsy and uninviting, doing to much, which is
reflected that there are few people willing to put their time into it.
At the same time, the comprehensive user guide is starting to lose its
importance, since almost all users are familiar with basic user
interface concepts such as windows and menus. You might even assume
that most users are familiar with a standard menu layout (file, edit,
view, window) and that this does not have to be explained.
In this sense I see a bright future of webcasts. Short how-to like
videos that show you, step by step, how to perform certain tasks. The
division into steps is a good idea, because associated with the
webcast comes a short document that sums up all the actions (and
ideally you could click on one of them to jump to the specific moment
in the webcast video).
With this message I haven't even started discussing about how to
integrate the help documentation into the system.
There is so much to think about. If interested people are willing to
get something up and running; come up with a plan, get something
going, show your results and we can work from that. If you want a
wiki, come up with some articles, then ask the web team to host you
within the haiku-os.org domain. I'm sure they will look into
facilitating you if you have a good start.
Niels
Other related posts:
