[Developers] Feedback on the docs

[Shug Boabby]

Hi all,

I was asked on the freebase-suggest list to give some feedback on the
docs. I assume that they meant the freebase docs and not the
freebase-suggest docs, given the context of the message.

Some feedback on the docs:-

# what is missing

how the ids/names etc relate to Wikipedia, IMDB or Freebase URLs. I
found it very difficult to work this out, and only discovered how to
do it by asking on this list (for wpid) or by playing around (by wp
key). For example, the examples tend to skip over what you can do with
the various ids once you have them.

I found the queryeditor to be very very useful, I'd suggest talking
about it a lot more instead of encouraging programmatic access in the
tutorials.

# what is confusing

the examples in PHP confuse me, because I am not a PHP coder and I
found this to be heavily language dependent. I was much more
interested in just the JDOM syntax and didn't need to be confused by
code boilerplate.

the entire Trans manual confused the hell out of me... I'd suggest you
start it with an example of obtaining an image id from a JDOM call and
then showing how to obtain the actual image through a simple browser
URL call. Similarly for other content.

# what is simply incorrect

Some out of date stuff such as the licence/cookie arrangement and the
need to escape quote marks in ~= searches.

But I found the docs to be quite good in general. Being a Sting fan
certainly helps ;-)

I have 2 RFEs, do I need to log them somewhere?

1 - When returning ranked results, it would be incredibly useful if
there was some score that measured the popularity of an entity. For
wikipedia articles I would imagine the "number of edits" would be a
good indicator... usage stats would be awesome ;-) I find the
Wikipedia ID to be a crude measure of popularity, as obviously the
more popular stuff was added early (although, due to the cultural bias
of the Wikipedia editors in the early days, this does have some really
weird side effects).

2 - It would be awesome to be able to send off a "fuzzy text match"
query. I tend to use combinations of "a:key~=" etc, but it would be
really really good to be able to basically do a search engine style
search across the keys that can perhaps do simple things like stemming
of words, removal of stop words, rearranging words, minor spelling
corrections, alternative words and arbitrary dropping of some words in
longer queries... like one would expect from a search bar. I believe
Apache Lucene does much of this. As a solid example, I would like it
if a search for "smashin pumpkins" [sic] would return "The Smashing
Pumpkins", or if a search for "The Queen of England" would include
"Elizabeth_II_of_the_United_Kingdom" along with
"Elizabeth_I_of_England".

Thanks for an absolutely incredible incredible resource! Making the
database available for download has finally given me the confidence to
be able to use your API... at least this way, I know I could attempt
to come up with a workaround if your server ever got as unreliable as
twitter ;-)