* 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
|