Re: [naviserver-devel] Documentation & website question

[Zoran V. <zv...@ar...>]

On 05.09.2006, at 16:28, Bernd Eidenschink wrote:

> The general problem is: We don't _want_ to write documentation. Not  
> for man
> pages and not for the Wiki.

... so it is the attitude and not format that we're fighting with.
And given the low(est possible) attitude we need to make it as
simple as possible.

For long time I wanted to create a set of templates for each and
every ns_xxxxx command for somebody (even myself) to start adding
some content there. Because, without adding content to whatever
formated file, there will be no docs.
And by just lumping together all available html into one place,
you just "organize a disorder" creating even more disorder.

If we want to have documentation:

   a. we should split techical ref from howto (as stephen correctly  
pointed out)
      (the b. to c. below handle only the former)

   b. we whould employ some stupid and easy format everybody can  
handle which
      is capable of expressing enough formatting rules so we can get  
a decent
      looking nroff and/or html

   c. we should start adding (by copying or writing new) content to  
those templates.

Without b. and c. we will have no usable documentation!

I totally neglected the C-API so far as this is "roughly" collectable by
gathering function level comments for Ns_XXXX functions from C-sources.
OTOH, the Tcl API isn't.

Cheers
Zoran