[Developers] Updating the API Documentation

[David Flanagan]

Will Fitzgerald wrote:
> Phil,
> 
> Actually, that's the opposite of what I suggested. I think it would be
> very nice to have a clear, complete, formalish document describing the
> query language. This is currently embedded in the general tutorial
> document.

Will,

I'm the author of the MQL tutorial, and am currently working on an 
update to it.  There was enough new MQL syntax to document that I have 
had to restructure the tutorial.  You'll find that the new version is 
less free-flowing and somewhat more formal.  Nothing approaching an 
actual specification, but closer to what you're asking for.

You mentioned in your first message that the MQL material is kind of 
"buried" where it is.  Part of the reason for that is that my MQL 
tutorial is Chapter 3 of a book-length document titled "Developing 
Metaweb-Enabled Web Applications".  I had hoped that there would be a 
download link for the entire PDF, but currently the document is only 
available in chunks as freebase topics, so I can see why it feels 
somewhat inaccessible.

	David Flanagan


> I'm not against tutorial documents, and I certainly like lots of
> examples (including in standards documents), but I was suggesting
> something different.
> 
> The idea of a user-created Pastie-like site of queries and results is
> also a good idea (Martin Dudek's suggestion).
> 
> WF
> 
> On 5/30/08, Phil Gochenour <phil at metaweb.com> wrote:
>> Hey Will,
>>
>>  I totally agree; a basic MQL tutorial that includes an intro to the Query
>>  Editor is one of my main priorities, and I hope to have it together in the
>>  next several weeks.
>>
>>  Thanks for the suggestion, it definitely helps with ordering the
>>  documentation priorities.
>>
>>
>>  p
>>
>>
>>
>>  On 5/30/08 4:19 AM, "Will Fitzgerald" <will.fitzgerald at pobox.com> wrote:
>>
>>  > The biggest challenge to me has been understanding the semantics and
>>  > syntax of queries. It's covered pretty well in the tutorial, but it's
>>  > somewhat buried there. Bringing all of this out into a formal
>>  > specification/api documentation would be very good.
>>  >
>>  > On 5/29/08, Phil Gochenour <phil at metaweb.com> wrote:
>>  >>
>>  >>  Hey everybody,
>>  >>
>>  >>  If you read the Freebase blog you've probably already seen my little intro,
>>  >> but in case you haven't, I'm Phil, the new documentation manager, aka Doctor
>>  >> of the Docs, here at Metaweb. Over the next several weeks I'm going to be
>>  >> doing a little clean-up on the API documentation, and wanted to see if you
>>  >> all had any comments, suggestions,  etc,. on anything from the document
>>  >> content to the way it's organized. My main concern is making sure that it's
>>  >> all consistent and accurate, and I'm guessing that you all have far more
>>  >> experience in working with it than I do. Also, if you've got any other ideas
>>  >> or feedback for other developer documentation, I'd be happy to hear from
>>  >> you.
>>  >>
>>  >>  Looking forward to working with you all in the future,
>>  >>
>>  >>  Phil
>>  >>
>>  >>
>>  >> _______________________________________________
>>  >>  Developers mailing list
>>  >>  Developers at freebase.com
>>  >>  http://lists.freebase.com/mailman/listinfo/developers
>>  >>
>>  >>
>>  >
>>
>>
>>  _______________________________________________
>>  Developers mailing list
>>  Developers at freebase.com
>>  http://lists.freebase.com/mailman/listinfo/developers
>>
> 
>