* The situation right now: DocBook/XML

NetBSD has a lot of online documentation, in various formats: some pure 
HTML, some legacy .list files (that are turned into HTML by a perl script) 
and most recent files are written in DocBook/XML. The Guides (NetBSD 
Guide, Internals Guide, pkgsrc Guide) have a special state here, as 
they're mostly standalone documents that are intended for printing, in 
addition to publishing on the web.  The problem with the current situation 
is that the toolchain to handle the DocBook/XML docs is to heavy: it 
requires htdocs being checked out, a proper set of tools installed in a 
version that actually does work, plus DocBook/XML formatting knowhow. As a 
result, I see many people being reluctant about updating documentation, 
pushing things on the NetBSD www team or not doing it at all. Plus, 
adding/updating documentation is only available to people with NetBSD CVS 
(write) access.

  * The Wiki approach

Given my experiences from Google's Summer of Code Mentor Summit and
also some other recent work, I've played a bit with Wikis, in
particular with MoinMoin. Having things online and just needing a
click on "Edit" saves the problems of having htdocs checked out and
tools installed, and depending on the formatting language, even
DocBook/XML knowledge may be superfluous. As such, Wikis sound like a
good alternative.

There are several challenges, though: migration of existing
documentation into a Wiki is one (MoinMoin offers some XSLT processing
support here, and even using DocBook as the wiki language).  One
problem that's solved nicely in XML is that of template pages: in XML
you define a number of variables, and have them rendered according to
the template. Change the template, re-render, and you have a new
layout; This is currently used on the ports homepages in htdocs/Ports
and the htdocs/contrib/projects.xml page. In the Wikis that I've seen
(MoinMoin, mostly), you can define a Template, but once you
instantiate it into specific pages, it's fixed and you can't change
the layout later. Which is suboptimal.

So, while XML is heavy to use, it has advantages on the rendering
part, while Wikis score for editing but are limited in flexibility
(unless someone digs in really deeply).

  * An idea: A wiki frontend to htdocs

Now my idea was: what if we had an easy frontend to htdocs, that
allows browsing and editing files, supports converting XML to HTML,
and goes out of the way otherwise? Or in other words, a Wiki frontend
for htdocs, that fires up a web-based editor for the XML files when
you click on 'edit', and that translates things into HTML when you
press the 'save' button.

  * Other considerations

Of course there are many other aspects to consider in that scenario:
personally I wouldn't insist on a web frontend, but it would make
things for a few people easier. Security of the whole thing would be
interesting, esp. making sure noone could compromise the htdocs CVS
repository. There are probably many other, but the idea is to improve
NetBSD's documentation, and make it easier for developers and user to
work with.


  - Hubert