Re: [naviserver-devel] Documentation & website question

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

On 04.09.2006, at 22:51, Vlad Seryakov wrote:

>
>> I see the docs in two parts, the man pages, which are a technical
>> reference, and the HOWTO stuff.  Seems to me like the technical ref
>> should be kept uptodate with the code, and the HOWTO stuff on the
>> wiki, where people can, hopefully, update it.
>
> Even technical pages, having them quickly on the same server you are
> working under /docs or /_docs or /whatever with search could be  
> easier,
> i like man pages but cross referencing and quick access is not  
> their best

Allright: cross-referencing is of course miserable.
But as I'm most of the time on command-line, a proper usage of
'apropos', 'man' and 'grep' solves 95 % of my needs. I never
saw ANY other Tcl documentation (apart from very first book
from JO).

>
>> Pointing people in the right direction is a good idea though.  How
>> about a default start page for the installed server which focusses
>> more on what to do next, rather than advertising?  Could point to the
>> installed html version of the docs with a file:/// reference, and the
>> online wiki for HOWTO stuff, talk about the reference config file,  
>> and
>> the the stats module can be enabled for introspection stuff.
>
> I do not see where to point now, too many pieces around, so i think
> about one repository for all docs, better under CVS so changes can be
> tracked and all docs easily retrievd by one cvs command.

This also speaks for centralized reference docs to which I agree.
But the HOWTO's are best done under Wiki where others may add more
salt.

Zoran