Re: [naviserver-devel] Documentation & website question

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

On 05.09.2006, at 17:24, Vlad Seryakov wrote:

> b. is doctools i suppose, format is simple enough and has many formats
> to convert.

I would wote for that.

>
> documenting commands is okay, but man pages are needed to those who
> already developing something and knows what to look for. Top level  
> docs,
> like overviews, guides and manuals will make documentaion user  
> friendly.

Yes. This is what I'd do in Wiki. After all the Wikipeida does much more
content that we'd do in 1000 lives, yet still all is done in Wiki
(amazing, isn't it?).

> I found in my hard drive old circa 2002 aolserver docs, including C- 
> API,
> Tcl-API and other overviews. Not bad documentation and still  
> apllies to
> naviserver as well. It is html already, converting it to doctool does
> not make sense but not using it does not make sense for me either. And
> correting these old docs is not that hard, the question is: where  
> we put
> it? CVS? SF mane page? Wiki?

Wiki.

>
> For the problem where do i start: man pages or Wiki or another  
> document,
> too many different ways and still it will be kept in pieces in  
> different
> places.

Both :-)
We (I'm afraid to say I) can start ref-doc immediately and
never finish (i.e. we just add content as we *can*).

The "bad" thing about the other (Wiki) is: it just takes
lots of time! I personaly can add to the ref docs by
filling in the man pages but I can't write top-level
overview type of docs. I just have no time for that.

OTOH, I would be more than happy if we just manage to get
the Tcl API completely documented!

Cheers
Zoran