> I agree with that 100%, however when it comes to the question I raised, how > do we document the version for php as there is beta's and the such do we > start documenting now etc, shouldn't this be a doc team problem? > I'm pretty new to this list so I'm not sure how things work etc but that's > just the way I view it, however if things are done differently please feel > free to put me in my place > I havn't thought it through, but branching phpdoc might not be an awful idea. (Or it might....)
For myself, when I add a new function/change the behavior or a function, I document it immediately. In some cases (dns_get_record() pops to mind), this means that it's in the documentation WAY before it's in public consumption. (That one's been there almost a year and it's a PHP5 function). Some people outright miss the "(PHP5 CVS Only)" tag at the top of the manual page, others don't understand "(No version information, may be only in CVS)". Waiting to document functions until the release they appear in minimises that confusion, but it does disservice to those who are looking to prepare for the next version. It also creates a BIG problem when it comes time to release and those who wrote the new functions are no longer available or have forgotten that innane bit of trivia that's important for the manual page. Can I keep the manual page local until release? Sure, but then how are other documentors going to know what's been done and not duplicate effort? Will I accidently delete/loose the files in the mean time? Oh, and don't forget about translations. These guys need some lead time to do thier work In fact, knowing about new functions in comming versions is just the kind of propaganda needed to get people excited about upgrading. For new functions, the user will try it and get an "unknown function" error. They can look at the manual page again (and hopefully see the version tag this time) or ask on [EMAIL PROTECTED] For modified functions, It's important to address the change as a note. i.e.: The xyz parameter is not available in versions prior to PHP 5.0.0 In both cases, we rely on the user reading the documentation and seeing the version number. But is that really so much to ask? But back to the idea of branching... We can satisfy all of the above needs (even have a second build for those who want to read "HEAD" documentation) by adding branches to phpdoc, but that means changing the way the documentation in maintained, and may cause issues with the translations.... Talk amongst yourselves..... -Sara
