Re: Documentaion (Was: [PHP-DEV] PHP File Upload Security Hole - Still No Fix?

Ron Chmara <ron@opus1.com> wrote: > Go to a bookstore. Look in the computer section. > Now ask yourself: Why are there all these books, if documentation is > so simple as to write one, complete, set, without ever having to revise, > republish, rework. You seem to be confusing books and documentation. Very few of the books in the computer section of the bookstore are documentation. Certainly very few of them are *authoritative* documentation. WordNet tells me that 'documentation' means: documentation n 1: confirmation that some fact or statement is true [syn: {certification}, {corroboration}] 2: program listings or technical manuals describing the operation and use of programs [syn: {software documentation}] > Documentation _has_ to be dynamic, and this means that it will not always > reflect the current state of the program. There is no program, in existence, > that I am aware of, where the entire program is completely documented. I am not complaining that PHP is not completely documented. I am taking issue with the people who don't even know what it would mean if it was. I have also pointed out a few places where the need for documentation is particularly acute because it involves security issues. I'm not going to apologise for that. > To put everything in there, all in one place, would be impossible to do > in any reasonale fashion. We'd have to write descriptions for Perl > folks, HTML folks, Joe-PHP-is-my-first-language folks, etc. No, you simply need descriptions for people-who-read-English folks. You can add extra stuff to help people migrating from Perl, etc, but that is not part of the core documentation, it is a helpful extra bonus. You may think it is important, and I'm not going to disagree, but it is not the same thing.