[openbeos] Re: On the new Haiku website
- From: "Niels Reedijk" <niels.reedijk@xxxxxxxxx>
- To: openbeos@xxxxxxxxxxxxx
- Date: Thu, 17 Aug 2006 16:59:27 +0000
> In our stage, i also think the Wiki is better. It applies for Doc
> format,
> Hosting,
> and Submit policy. When the documentation gets more robust, we can
> translate, then modify it in the DocBook format.
I beg to differ. I think the docs have to be in our subversion
repository, and they also should be in DocBook format, so that we can
easily squeeze them to any format we desire (HTML, PDF, ...). It should
just be a build option to include the docs in HTML format, for example.
HTML, PDF and? I see where Docbook provides good tools to export in
different formats and layouts, however, I really doubt that besides
HTML and PDF there is little to export. HTML could serve as a base,
the HTML can be transformed into PDF (print to pdf?) Scripts could be
made to combine several HTML files into one.
I don't think the technical merits of docbook weigh up against the
learning curve at this point in time, with no one understanding it, or
even knowing how to structure the documentation. Read what I'd do
below.
It's really no big thing getting used to version control, and it makes
the whole process much better controlled and productive. The last
documentation team was a desaster from my POV, and I certainly don't
want to repeat that again. We absolutely need good documentation, and
it has to be written in a controlled and professional process.
Writing documentation in a controlled and professional process isn't
achieved by version control and docbook. It's done by the people that
set up efficient and proper ways to use tools (any tools - be it wiki
or docbook). I don't really know what happened last time with
documentation (was there ever a documentation team?), so I can't
respond to that particular situation. However, I think that in the
process of getting good docs, you need to find out what works.
Right now there are probably a dozen people lurking about, waiting for
their chance to do something. Only a handful of those people will
actually have the proper skills for doc writing. I think no one
actually has any experience (besides me, but my main thing was
translating). You could try and set up a documentation team, that
first discusses what they are going to do, how they are going to do,
what conventions are needed, etcetera, but that would probably end up
in endless loops of people discussing things that they have no
knowledge of anyway. End result: a lot of rules and regulations and
nothing to rule and regulate.
A better approach would be, IMO, that if there are a few people that
want to help out, start setting up an outline of how the documentation
should be. Preferably, everyone does it on his/her own and later on
compare and discusses the most ideal situation. They can also start
writing it, and in the way finding out what works and what doesn't. A
few probably will have to step out for having no talent or quality for
doing this work, but similarly a few people with excellent
documentation skills will get up. At that point, they might be able to
start to think about their conventions, the process, the tools and so
on.
So, to sum things up, I'd suggest using a part of the wiki or opening
a new one for people that have ideas about how Haiku's documentation
should be structured. Let's propose a few concepts, have someone
oversee the process, and start with creating a beginning. At a certain
point in time it will be clear that certain people excel, give them
'power' to start leading the documentation project and start setting
up the controlled and professional environment.
Or better yet, hire Lauri Watts. She's the amazing person that started
KDE's documentation machine. :-)
Have fun!
Niels
Other related posts:
