Re: Interactive docs idea

Alvaro Herrera <alvherre(at)dcc(dot)uchile(dot)cl> writes:

> > So there's no comments saying "here's a useful function written using this
> > function" or "watch out for this common bug" or "if what you want to do is
> > this you might want to check out this other function" or any of the thousands
> > of similar comments in the PHP docs.
>
> You are right, there aren't. But to me that's not a bad thing. I'd
> find PHP's manual much better if the main text body really covered the
> subject instead of only showing a couple of examples, and leaving part
> of the matter to the comments (Even to "editor's notes" in the
> comments!)

I think this is a false dichotomy. Nobody's arguing that we should let the
main body of the documentation rot in favour of the comments. There's no
reason we can't have more comments and still have nicer authoritative
documentation than the PHP folks :)

I really see the comments serving a separate purpose from the main body. The
main body should be the manual -- an authoritative reference. The comments
should be more like this mailing list only organized.

How many times have you seen a question on pgsql-general and thought "gee that
would be answered if only the poster searched the archives"? Well the comments
on PHP serve basically as an organized repository of such previous discuss.
Instead of being in a single archive to search through they're attached
directly to the relevant piece of the documentation.

Certainly comments that amount to bug reports about the documentation can be
addressed by fixing the documentation (and the comment can then be removed).
Likewise comments that suggest additions can be moved into the main body of
the documentation.

--
greg