> -----Original Message----- > From: Sara Golemon [mailto:[EMAIL PROTECTED] > Sent: Thursday, December 04, 2003 5:13 AM > To: Jared W > Cc: [EMAIL PROTECTED] > Subject: Re: [PHP-DOC] Re: documenting php5 > > > 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)".
I have yet to see a function with this on it maybe I am just blind, most functions I see have the no version info may only be in cvs which is down right confusing what cvs branch for one ;) > 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. Also makes a problem to bug test the new functions if you cant find them, and people have problems reading the manual let alone a changelog. > 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. As mentioned before there is the changelog but that's often a pain to track down, anon cvs and the such much easier to goto say php.net/php# > 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] And get told to RTFM ;) > 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? Not really but as you said some params wont be in it and may be buried in a user comment or the such, generally the docs team is good with staying on top of things but these things do happen. Maybe separate strings for separate versions but this again is a hassle on the documenter and creates a mess in the docs, colours are always nice ;) > 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..... Good idea, but as you say a pain in the arse specially when it comes to merging especially user notes ;) and the need doesn't arise to often mainly around a major release I would assume > -Sara jared
