Subject: NetBSD Documentation Framework - how to do it
To: None <netbsd-docs@NetBSD.org>
From: Mike M. Volokhov <mishka@netbsd.org>
List: netbsd-docs
Date: 12/11/2006 13:50:23
Greetings!

This is a well known fact that our www (htdocs) is stagnated from
technical POV. Fragile and heavyweight toolchain, content mess,
broken standards - all these discourages developers and users from
further contributions to www and any of guides.

Several people (including me, and thus you can reasonably blame me
for this) has had proposed some ad-hoc solutions in this area.
Two approaches has been mentioned most often:

  - cleanup of our DocBook/Website XML based framework
  - migration to Wiki

While both ways have a lot of pros and cons (in this letter I'll
say nothing about them), it seems really hard to find someone who
can take care on any of those approaches (i.e. he/she would have
enough of interest, knowledge, and time). Moreover, discussing this
topic a hell lot of times we still unsure about tools to use. (!!!)

Interesting, that other *BSD projects mostly have just the same
problems.  Such, browsing the freebsd-doc@ arhives I've found that
FreeBSD is stagnating on good toolchain too (just because it uses
the same tools as NetBSD). BSD Certification group is also unsatisfied
with processing methods of their docs, including reports writing,
website management, and so on (project uses custom made PHP-based
site and OOo for papers). I'm dunno for DragonFly BSD and OpenBSD,
but looks like both sites using plain HTML with some addons (awk
postprocessing for OpenBSD, SSI for DFBSD), and I bet they're
somewhat unhappy with this. As opposite, DesktopBSD site is build
on top of TYPO3; the DocuWiki is used to serve documentation area.
PCBSD rely on [unknown/custom] PHP/MySQL based CMS and their guides
looks like a cleaned up DocBook output (although it may be just
custom made too). Think about authoring, mirroring, translation,
publishing, and other usual tasks - and you'd see that current
documentation tools are far away from good. Sigh.

The problem looks common enough. So let's start solve it with some
good questions here.

  - Is the current documentation processing a problem?  Yes, it is.
  - Is it solvable problem?  Yes, it should be (in any meaning).
  - Do we have someone who can solve it for us?  May be, who knows...
  - What can we do then?  Find that good people! :)
  - How?  Via creation of BSD Documentation Working Group.

This group would include all the people who interesting in high
quality documentation framework for *BSD operating systems - guides,
articles, web-site, man-pages, and more. The Group will have
following goals:

  - Define the need, determine the problem.
  - Find the solution - ways, approaches, tools...
  - Adopt existing or develop and implement the framework.
  - Create migration plan and assist in migration to new documentation.

Why the Working Group? Simply:

  - More man power
  - More knowledge and experience.
  - More wide view on the problem.
  - More control and more buy-in from [not involved] developers.

And as result:

  - Framework will better fit our needs (in any meaning).
  - Faster development speed with higher quality.
  - Less dependency on particular people.
  - More chances to develop this framework at all.

Ok, so what such group will need? Where to find people who will be
interesting in this? As I've already said, the problem is common.
Thus, to address it I'll prepare and sent a proposal letter (similar
to this one) to all mentioned projects. Moreover, the problem covers
not *BSDs only - many other open source teams developing a good,
but completely documentaion irrelevant tools, and hence requiring
such framework a lot.

But before all, I'd like to know your opinions on this topic. It
would be really silly to sent the wide proposal without getting
buy-in from you, NetBSD documentoraptors, first.

--
Kind regards,
Mike M. Volokhov.