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.
|
