Several weeks ago an announcement was made on php.net that the new documentation build system was ready for testing. The announcement encourages everyone to use and test the new system. I should have started using it then, just to help out and find bugs, but I glanced over the new manual and didn’t really give it much thought. In the last several days I noticed that the php.net manual display had changed, which reminded me about the new manual, and have since switched. The new manual is located at: http://docs.php.net/manual/ (still in test).
First I would like to say that I like the look of the new manual; it seems cleaner with well defined areas. For example on a function description page the description, parameters, return values, errors/exceptions, and examples all appear in their own ‘box’ (div tag) with a light blue background. This definitely makes it easier to locate what your look for and generally gives a nice presentation of the information.
My two gripes about the new manual are fairly petty. I think it is a case of ‘Who moved my cheese‘, instead of actual issues with the manual.
Gripe 1: There is too much spacing between items in the unordered lists.
Looking at what I believe to be the CSS styling for the ‘li’ tags, they have added a top and bottom padding of 3 pixels (6 pixels between each line). Although this makes for good separation between each item it also makes the pages longer and consequently more scrolling.
Gripe 2: The new navigation system, specifically in two areas:
- The index page of the manual. The old index page, was basically like an extended table of contents. It listed the sections of the manual along with the major subsections. This was always my starting point. You may not find exactly what your looking for in the first click but you knew where you wanted to go. The new index page, contains the list of sections in the left-hand navigation bar, but the page does not list any subsections. New users of the language I believe will find it more difficult to locate the information they need simply because they may not know exactly what their looking for. Now, of course, users already familiar with the language will still be able to find what there looking for but it will take more clicks to get where your going, specifically for the function reference section…
- In the old manual when you viewed the function reference section you were presented with a long alphabetized list of groups of functions; Arrays, MySQL, Strings, etc. Now they have grouped the groups; array functions are listed below ‘Variable and Type Related Extensions’, string functions are listed below ‘Text Processing’ and MySQL functions aren’t actually listed on the page, they are under ‘Database Extensions->Vendor Specific Database Extensions->MySQL’. Now I am all for more organization, but by grouping the groups the function reference is no longer alphabetized and the added clicks needed to get to the section you want I feel is not a bonus.
- This also comes into play after you have chosen the section you want. For example, in the old manual you could be looking at the array functions, find what you need, and just leave the browser open to the array functions page while you went back to work. Then after a bit more work, if you needed to look at the string functions, you could simply click the ’string’ functions link in navigation bar and be there in one click. This is not possible in the new manual…Given the same situation you always need to go back to the main function reference page and start drilling down from there.
I don’t want this to come off as a bashing of the new manual, these are minor issues and I probably just need to get used to the new setup. So now that you read my review, let us know what you think of the new manual.
PDF
