Re: [naviserver-devel] hey hey wiki

[Bernd E. <eid...@we...>]

Hi Stephen,

> I was thinking the wiki might be best suited to task-specific
> documentation?  For example, rather than list all commands and give an
> example of each, we might have a page 'Returning Data' which shows how
> to use ns_return, ns_returnfile, ..., how to write headers and stream
> content with ns_write, how to choose between them, etc.  Then we might
> have a page called 'Performance Tuning' which would describe which
> config file settings affect performance, settings for your OS, how to
> use the stats interface for gathering data, etc.
>
> The formal API documentation in CVS will be the first place to go when
> you have a specific question about how the server works.  When you
> have a goal in mind -- tune the server, write a form that accepts file
> uploads, set up virtual hosts -- you'll read an article on the wiki.
>
> Makes sense?

Think it would be a good combination to combine the two approaches!

My suggestion was to present a (somehow) complete list of commands including 
their categorization as kind of a showroom of possibilities.
If they are adequately grouped 
* new users can find commands they need in a context
* learn about more and other ways to do things
And finally I found that lots of good advice, corrections and discussions 
comes from users using the commands to solve individual problems: Just take a 
look at the commented PHP and MySQL Documentation!
If that would happen here it would be a great bonus!

With the wiki approach it's very easy to link to pages that fit for your 
suggestion of Best Practices and HowTo's, e.g. we could do

...
* ns_returnfile: <Link to 'Returning Data'>, <Link to smth. else>, ...
...
* ns_write: <Link to smth. else>, <Link to 'Returning Data'>, ...
...

So everyone could get the use of commands in different or similar contexts.