Alvaro Herrera <[EMAIL PROTECTED]> 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 ---------------------------(end of broadcast)--------------------------- TIP 7: don't forget to increase your free space map settings
