The documentation is very difficult to use for a couple of reasons.
Firstly, to do anything with the API, the entries for that process are scattered in many places.
Automated tweet (status) posting, for instance: To learn how to do that, one must look in these separate sections:
1. How to get an access token from Twitter
2. How to send an OAuth request
a. What oauth_nonce is
b. What "oauth_signature" is, how it's formed and the valid encryption protocols
3. Where to redirect the user
4. How to post a tweet (status)
5. How to interpret the responses from all the above
That’s a lot of different navigating to perform a single, seemingly boilerplate operation.
What I would recommend is creating a collection of common use code scenarios [in an arbitrary programming language] which describe, from beginning to end, how to perform the most common operations for Twitter.
The second reason is that there aren’t any libraries for the API distributed by Twitter itself. If there were, the need for so much documentation would be relieved. As an example, I didn’t need any documentation for integrating Facebook because downloading their PHP library and looking up a single example took all of 15 minutes.
I’m aware that there are 3rd party libraries, but they aren’t comprehensive. The “Abraham” Twitter authorization library, for instance, requires an access token and secret - which means that it doesn’t cover user context automated operations.
The authorization process is certainly the worst part; I didn’t even realize you guys still used OAuth 1 until I found out here. But frankly, that the operations described (e.g. search, status post, DM receiving) aren’t explained top to bottom in the documentation spaces is the reason figuring anything out is so challenging.