Documentation suggestion
| From: | Jason Rogers | Date: | Mon, 16 Feb 2004 22:02:08 +0000 |
| Subject: | Documentation suggestion | ||
| Groups: | php.mirrors | ||
| Request: | Send a blank email to php-mirrors+get-23534@lists.php.net to get a copy of this message | ||
I have noticed that the online documentation lists the supported php
versions for the particular feature you are currently reviewing. It also
lists all the functions to the left. Both of these documentation features
are good, but there can be a problem with users with a particular version of
PHP in mind.
Take for example somebody looking at image functions. The function
"imagecopyresampled" works only with php >= 4.06 while "getimagesize" works
with both php 3,4.
If somebody were looking for php 3 specific functions, they would have a
hell of a time looking at the documentation because the list of functions to
the left would keep showing php 3,4, 5 functions when they are only
interested in php 3.
I think there ought to be a mechanism put in place to remove references to
documentation which is incompatible with the version of php being looked at;
php 3 users should be able to look up php 3 documentation. Php 4 users
should be able to see everything that works for php 4. When php 5 comes out,
have php 5 specific documentation available.
I do like having the info on what versions of php support a particular
feature. For instance the listing of "getimagesize" as being compatible with
php 3 and 4 is useful if I were to regress to php 3 (for some strange
reason).
I would think that you could have a drop down menu next to the text field
for users searching the documentation which would have version numbers
available. For the documentation page, you could simply add links for each
version. In both cases, you could also have an "all versions" option which
would display the documentation for php without filtering features to match
a specific version number.
I think it would make an already great language easier to work with if the
documentation would be viewable in a version specific context.
-Jason Rogers
Human Factors Research and Technology Division
Human Information Processing Research Branch
NASA Ames Research Center
http://human-factors.arc.nasa.gov/ihh
http://pbagroup.arc.nasa.gov/