[Developers] Feedback on the docs

[David Flanagan]

Shug,

Thanks for the feedback.  I think that you are mostly referring to the 
MQL tutorial that I wrote, so I'll respond and ask some followup questions.

Shug Boabby wrote:
> 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.

This isn't a use-case I'd ever considered: going from freebase back to 
Wikipedia.  But it probably is worth mentioning the /wikipedia/en_id key.

> 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.

The problem is that the queryeditor, like everything on the freebase.com 
website is still a moving target.  The programmatic API is stable, and 
that is what this documentation is supposed to cover.  The query editor 
is quite useful, and I do refer to it in the documentation, and I expect 
readers to use it to try things out.  But I can't really document it, 
since it isn't stable yet.

> # 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.

I have to assume, however, that the PHP coders out there will appreciate 
that example.  (There's just one PHP example in my tutorial.)

> 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.

I'm updating that section right now.  It would probably be helpful if I 
started off with a few example URLs for retrieving images and documents.

> # what is simply incorrect
> 
> Some out of date stuff such as the licence/cookie arrangement and the
> need to escape quote marks in ~= searches.

I'm deleting all the license stuff as I update the document.

The issue of escaping quote marks in ~= patterns is an unfortunate one. 
  The MQL rules changed and are now changing back, I think.  I believe 
that the final word is that ~= matches look for phrases implicitly and 
that quotes are not necessary.  If you want to match multiple words that 
are not in a phrase, use multiple ~= matches, with property prefixes. 
Having said that, however, I'm not sure whether that is the current 
reality: last time I checked you still needed to quote phrases...

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

Thanks!

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

I can't comment on this part of your message.

Thanks for your feedback!

	David Flanagan

> 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 ;-)
> _______________________________________________
> Developers mailing list
> Developers at freebase.com
> http://lists.freebase.com/mailman/listinfo/developers
>