View Full Version : learning a new API through Documentation only

07-19-2010, 08:14 PM
An interesting question has recently crossed my mind while trying to learn to use the new "Open Source Media Framework" API; "How do you 'effectively' learn an API through it's documentation?". I've always been a bit confused as to how to go about learning a new API. Most of the time, when I'm trying to learn it, I just type in google the API's name, with the word "tutorial" on it, or buy a book on it. The results are varied; some has tons of tutorials, and some with next to none. But sometime there are only a small number of tutorials that are real gems to find. But how do those people, who write these tutorials, know so much about the API when there is only documentation they can look at? How do they do it? Where do they even start? etc?

Are there any sites or anyone on these forums that can give pointers on constructive ways to learn a new API from just documentations.

07-19-2010, 08:28 PM
one sure way is to practice by making test apps, fail at those, practice some more, repeat until you've figured everything out... then, your an expert! (experience, learn through experience)

07-20-2010, 07:56 PM
To "effectively" learn something you have to real-world practice it.
People that write books or tutorials about subjects where there are not many contents available, is people that directly play with code, and generally are more experienced pogrammers.

07-22-2010, 07:15 PM
Learn how to read the documentations?

Flash (and Flex) reference is arranged in such a way that you can quickly find the API you are looking for, instead of having to look for a tutorial on something. This way, you can quickly address the issues you are having with one API without moving through a whole bunch of others.

So exactly how will you know how to use an API with just reading the reference for it once? Well, you read its inheritance tree. See what it was based off. The base behavior remains the same no matter how complicated the implementation is.

For instance, this is the inheritance tree of TextField:

TextField -> InteractiveObject -> DisplayObject -> EventDispatcher -> Object

From that, you can figure out that TextField was based off of the InteractiveObject API, or class (I prefer the term class so I'll use "class" from now on), which means TextField will expect user inputs from the keyboard, or mouse, or any other device that Flash supports. Then you see TextField was based off of DisplayObject (all InteractiveObject has to be visual for the user to see, and therefore, they must belong to DisplayObject), which means you can definitely add a TextField instance as a child to the display list and output it to the screen. Then DisplayObject is based off of EventDispatcher (this is by default because it gives you more control over the DisplayObject, and... I think you should get to know the EventDispatcher class more than any other class since you'll be using it a lot more than any other class), so you know you can expect events being fired off an instance of TextField. Last but not least, it's an Object, so you can expect it to have properties which you can read and access.

So from one look at the inheritance tree, you pretty much know that this TextField API will:
- expect input from users
- be able to output itself to the screen
- fire off events
- have properties which you can read and modify, and may have methods or functions which you can call to do awesome stuffs

That's pretty much enough for you to study it. The rest of the reference page will tell you which properties and methods you can call, and if you're lucky enough, you may even find examples on them.

The rest is just you experimenting with it to see how it really behaves in practical use, and how you can utilize it to do things for you.

Knowing your enemy is half the battle, and there is already a manual on all of your enemies (the API reference web site), so you should have been able to do this from day one, instead of looking at tutorials. Tutorials are nice for getting you started, but they are never the place for you to look at when you are looking to find out more advanced stuffs.