[openbeos] Re: On the new Haiku website
- From: "Niels Reedijk" <niels.reedijk@xxxxxxxxx>
- To: openbeos@xxxxxxxxxxxxx
- Date: Thu, 17 Aug 2006 14:58:07 +0000
Just thought I'd jump in, as I've been working on documentation for
another project. I actually worked on DocBook's for KDE. They were
very difficult, partially due to the fact that it required a rather
complicated toolchain of stylesheets etcetera. As I worked on
translations, another level of complexity was added with syncing. This
has been changed for the better at a later stage, when Stephan Kulow
wrote a parser that parses the docs using XSLT (I guess).
2006/8/17, Waldemar Kornewald <wkornew@xxxxxxx>:
Which format?
* DocBook
* LaTeX
* ...?
__ To me, DocBook sounds good.
DocBook requires some effort to get into. It's a nice format, but it's
limited in a way that it's not WYSIWYG and it requires a whole slew of
tools.
Perhaps it's better to keep documentation development in a wiki. This
means that everyone can contribute (and contribute small changes
simultaneously), there is version control without adding a lot of
noise to our subversion repository, and the information is readily
available. Plus, developers could potentially add hooks to the
documentation without having to learn DocBook or messing things up.
I'm not very knowledgable on' wikis, but there must be a way to get a
'snapshot' from the web and include that in the package as
documentation.
Hosting
* separate repos, so members can't mess with our source code?
* integrated with our repos, so it looks more official?
__ A very open documentation project there will be a lot of
contributors, so a separate repos would be better.
That would be another advantage of WIKI. When I first kicked in KDE
documentation, I had to learn the concepts of version control. I mean,
it's pretty obvious when you are a developer and you learn to think in
a certain way. But as a 'noob' you have to grasp the concept of
revision numbering. I remember really not getting around the fact that
revision 1.14 of a file really was for KDE2. Subversion is perhaps a
bit more 'normal', but really, branching is the next topic of
misunderstanding.
Documentation writing is probably a quite linear process, involving
little branching (it makes little sense writing documentation for two
releases at the same time).
Policy
* anonymous commits
* everyone gets an account on request
* you must send patches before you get repos access
__ I think the second option is the best.
I'm imagining a wiki where everyone can change and contribute, but
where changes are marked 'need-review'. You can 'earn' privileges by
contributing a lot. This means your docs aren't going to be marked and
you can review things yourself.
Plus the wiki would make it easier for the top contributors to have
co-ordinate their efforts.
Subdomains really never gave me the feeling of "unofficial". If it's
in a subdomain the offical project must have set it up. How can this
be understood as unoffical? And if you put "Unoffical" on every page
in the subdomain people will probably doubt that haiku-os.org is
official.
A slogan like 'community.haiku-os.org - the place where people help
people' in the logo or at the top of every page would be able to
signal what kind of area of haiku this is.
Besides, moderation can make it official.
Niels
Other related posts:
