NetBSD Documentation Framework - how to do it

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.

On Mon, 11 Dec 2006, Mike M. Volokhov wrote:
> 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 am member of the BSD Certification Group, and I'm not
aware of any 
dis-satisfaction with the tools used so far. How do you come
to that 
statement?

  - Hubert
    BSDCG

Hubert Feyrer <hubertfeyrer.de> wrote:
> On Mon, 11 Dec 2006, Mike M. Volokhov wrote:
> >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 am member of the BSD Certification Group, and I'm
not aware of any 
> dis-satisfaction with the tools used so far. How do you
come to that 
> statement?

I'm also a member of BSDCG translation teams and I know how
it's hard
to work with current docs. Also, I've discussed this topic
with Dru
several times. The overall conclusion is that BSDCG
documentation
maintenence will be a headache in near future, as soon as
some
critical mass of people and documents would be involved.

--
Mishka.

"Mike M. Volokhov" <mishkaNetBSD.org> wrote
  in <20061211135023.GA24056netbsd.org>:

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.

 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
 toolchain is not so complex and I think some of us can do
so like we
 maintain a compiler in the base system.

 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.

--
| Hiroki SATO

Hiroki Sato <hrsNetBSD.org> wrote:
> "Mike M. Volokhov" <mishkaNetBSD.org> wrote
>   in <20061211135023.GA24056netbsd.org>:
> 
> 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...

--
Mishka.