On May 30 of last year, I wrote a post that began with the statement that "the worst thing about PHP is the documentation".
That post got a decent amount of attention in the PHP world, and attracted a good bit of feedback, most of which boiled down to people telling me that I’m an idiot and that the PHP docs are the best thing since sliced bread.
I remain unconvinced. While the wiki-style user comments on every page are nice, the basic organization of the docs is a mess. Most of the really useful stuff about PHP is in the function reference, and that thing is just a giant mass of undifferentiated links, with no guidance for developers as to which modules to turn to in which situations. Eventually you find what you’re looking for, but it’s not as easy as it could be, or should be.
One of the comments on my post from last year came from Philip Olson, the editor of the PHP documentation. He took my feedback in the constructive spirit in which it was intended, and gave us an update on the future of the docs by telling us to be on the lookout for "Livedocs", the next generation of the PHP documentation. He even made a promise about when we’d see it happen:
[D]on’t worry, Livedocs will be out before Vista and that’s a promise 😉
That was posted on June 6, 2006. Windows Vista came out on January 30, 2007. Livedocs is still not "live". So the lesson here is, be careful what you promise 🙂
So why am I revisiting this issue?
Many of the commenters said something along the lines of "if you think the docs are so bad, show how they could be better". So, in that spirit, I present to you MyPHPDocs.com.
MyPHPDocs.com is my attempt to make the PHP documentation more useful by making it more organized and more personalized. Specifically, with MyPHPDocs.com, you can:
- Burn your own custom PHP docs: include the functions you use every day, strip out the ones you don’t
- Find what you need faster: the function reference is completely reorganized, with functions grouped together based on the problem they solve rather than a huge alphabetical list
- Organize your docs however you like: You can re-order the sections of your custom manual, and it will remember the order in which you put them. You can also minimize sections you use infrequently to further simplify the list; it’ll remember that too
- Share your custom docs with friends and colleagues: Once you’ve got things Just So, you can pass your custom docs to anyone you like simply by giving them a URL
Is MyPHPDocs perfect? Heck if I know. But it’s my response to the "let’s see how you would do it" challenge.
So now I’m looking for your feedback. Try out MyPHPDocs and see if it makes your life easier. And if you have feedback on it, or find any bugs, send ’em my way, I’d love to hear your thoughts!