I snarkily posted something to Twitter about a bit of UI weirdness I saw over at the php.net site. The various call-out boxes had/have gained the ability to fold up or down when you double click them, which interfered with my “randomly click and select text I’m reading” behavior.
Looks like it’s only temporarily, but is sounds like the documentation team is considering some AJAX/dynamic UI elements for the site.
With the standard caveat that it’s really easy to criticize someone else’s project that you rely on without contributing much to, this is an awful idea.
The manual, and more generally the documentation project, is one of PHP’s most valuable assets. It allows users of the system to overcome its kitchen sink approach to language design. Things I love about the site/manual are
- For most of the language and core modules we’re given a description of the function, copious examples, and common pitfalls (ex. places where
==will bite you in the ass)
- Functions are grouped together by common functionality. When a Google search lands you on a function that is kind-of/sort-of related to what you want, a quick scan down the left side usually reveals what you’re after.
The smart “see also” functionality, which I imagine was painstaking put together by humans and helps even more with the “almost found what I want” problem
Supports user comments which means there’s a lot of “hey, you probably wanted to do X just like I did, here’s some code”
The super clever
Renders in any browser, not just “the latest version of any browser”
What I fear about adding a bunch of AJAX features is the tendency towards slower pages and browser incompatibility that this brave new world of Web == AJAX Application we somehow created for ourselves. The worst case scenario I’m creating in my head is a MSDN style site, but with more animation.
What I’d Like to See
Before I get to the UI, the biggest improvement I’d like to see is better documentation of the “newer” Object Oriented APIs, such as The Reflection API. There’s some kind of irony in that the Reflection section of the manual only has a list of methods with no context.
It would also be nice if the Zend Framework docs could be ported over to the manual or put in a similar format, although I’m not sure of the political ramifications there as the relationship between Zend and PHP has always been a little muddy in my mind.
Now for my assumptions. The primary UI for any manual is search. The secondary UI for any manual is discovery. No matter what kind of UI improvements you make, page rendering speed is the most important feature. I want to find what I’m looking for fast, and then get back to coding.
The biggest surface area I see for improvement is the search results page. If you’ve slightly misspelled a function it’s useful, but otherwise it’s not doing much to help you find what you’re looking for.
Brainstorming Some Useful Things that Could be Done Here
If no function is found, list other possible function matches, but then take a stab at what I meant. For example, when I search for closure, none of those functions are what I’m looking for. The link to the site search isn’t much better.
Dovetailing off the above, if your internet site search isn’t better than Google, either improve it or use Google.
Better/smarter guesses in the function list would be appreciated as well.
As for the function/method listing pages themselves, if it’s not obvious I consider them almost perfect as-is. The only AJAX style feature that might improve things here is a quick rollover summary of each function in the left-hand column.
My main point in all this is improve the UI, don’t just add a bunch of me-too jQuery features and call it done.