[openbeos] Re: On the new Haiku website
- From: "Axel Dörfler" <axeld@xxxxxxxxxxxxxxxx>
- To: openbeos@xxxxxxxxxxxxx
- Date: Thu, 17 Aug 2006 19:36:37 +0200 CEST
"Niels Reedijk" <niels.reedijk@xxxxxxxxx> wrote:
> > > 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.
We may also want to export it to simple to parse XML files for editor
help texts, etc. - there are plenty of applications for this.
> 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.
[...]
> 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.
[...]
> 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.
We already have tried what you proposed with the first team, we've
already discussed what we want, and what's needed. We even have a start
of the documentation in DocBook format in our repository (under src/
documentation/).
While a Wiki might be good enough for end-user documentation (like how
to use preferences panel X), it's not for something like the Haiku
book. And I definitely don't want to see any documentation team working
without a version control system.
> Or better yet, hire Lauri Watts. She's the amazing person that
> started
> KDE's documentation machine. :-)
Yeah, why not ;-)
Bye,
Axel.
Other related posts:
