Subject: Re: NetBSD Documentation Framework - how to do it
To: Hiroki Sato <>
From: Mike M. Volokhov <>
List: netbsd-docs
Date: 12/13/2006 09:01:03
Hiroki Sato <> wrote:
> "Mike M. Volokhov" <> wrote
>   in <>:
> mi> Greetings!
> mi>
> mi> This is a well known fact that our www (htdocs) is stagnated from
> mi> technical POV. Fragile and heavyweight toolchain, content mess,
> mi> broken standards - all these discourages developers and users from
> mi> further contributions to www and any of guides.
> mi>
> mi> Several people (including me, and thus you can reasonably blame me
> mi> for this) has had proposed some ad-hoc solutions in this area.
> mi> Two approaches has been mentioned most often:
> mi>
> mi>   - cleanup of our DocBook/Website XML based framework
> mi>   - migration to Wiki
>  I am one of the people who are concerned about the doc framework, and
>  this was the reason why I joined the team so I should have been more
>  active in this area (sorry, all...).  Since I have difficulty a bit
>  in my real job, the cleanup work is going quite slowly.

Just the same for me :-)

>  Anyway, from my investigations about such frameworks in recent years,
>  I think the problem is maintenability of the documents in a source
>  form from average developer's point of view.  Maintaining the

Could you explain this bit more detaily, please?

>  toolchain is not so complex and I think some of us can do so like we
>  maintain a compiler in the base system.

A primary advantage of build-in toolchain (like in base system) is
stability. Every new gcc version creates a lot of PITA for developers.
Although our current toolchain is much more lightweight, it suffers
almost the same problems. I believe our framework should handle
this issue.

>  I am not sure creating a group for documentation work is effective,
>  but I think it is good to discuss such a topic with each other.

So let's do this in evolutionary way. For example, by creating
more or less independent project. But I'd like to see new
framework will be accepted by *BSDs, otherwise i will be a dumb
work. To coordinate people we need the following resources:

	- collaboration: repository, wiki, ...
	- communication: maillist, IRC channel, ...

I'm wondering who can help us with repo and maillist...