[Developers] Documentation urgently needs a wiki + Getting started with PHP

[Will Moffat]

I gave a demo of Freebase to some great Belgium PHP developers. They
totally got it and loved the concept. One of them was so fired up that
he started working through the tutorial at 4am.

It was not a positive experience.

Some of the problems:
* There is no visible feedback mechanism for the documentation pages.
At the very least a wiki or discussion system needs to be added so
that people share their problems. Even if all they do is to add a note
"This doesn't work" then that will save lots of pain and bad feeling.
* Some of the tutorials no longer work. It's very disheartening to a
new developer when the tutorials are buggy. Hello world apps must just
work out of the box. Developers new to Freebase just don't have the
experience to fix simple bugs and will just give up.
* It's easy to mess up cookie authentication, we need to emphasize
that developers should test this first.
* "Developing Metaweb-Enabled Web Applications" needs to be updated
with the API changes (results codes have changed which means examples
like albumlist.php are totally foobar)
* The tutorial apps are simple (which is good) but too fragile.
albumlist.php fails with PHP errors for queries like 'R.E.M' (missing
last period) or 'The Beatles' (more than one matching band). Somebody
new to Freebase will have no idea what went wrong.
* The help doesn't seem to be searchable. (It would be great if it was
exposed as static html without authentication and crawled by  Google.)
* If you receive an invitation, register but then lose the
confirmation email then you cannot access your account. The "I forgot
my password" does not seem to work in that situation.

Other minor issues:
* It would be great if the Query Editor generated queries as a mqlread
URL, a PHP query and a Perl query as well as JSON.
* Need a better error message if you call
http://freebase.com/api/service/mqlread without arguments. The error
should be 'missing query' not  the confusing "authentication required"

On a positive note:

I made a start on trying to improve the PHP documentation. See
http://hamstersoup.wordpress.com/
* Created simple shell and PHP scripts to test your Freebase cookie.
* Fixed albumlist.php, made it more robust and added a 'show query' option.
* Wrote step by step instructions for getting albumlist.php running

Your feedback would be very welcome.
regards,
--Will

PS It was the great documentation that got me into Freebase in the
first place. It's worth updating it!