Documentation problems


#1

Hi there. I tweeted at @TwitterDev and they said I should come by here. I’m a long-time dev but a first-time twitter-api dev, and I found the documentation scarily lacking for such a mature product. I don’t want to just come and complain, but as a first-timer, I’ll tell you what I saw and how it violated my expectations. To put this all in context, I was mainly building an app touching streaming API endpoints.

Since I’m a new user, I can’t post a post with a bunch of links, so I had to put spaces and break most of the links. Sorry.

Overall landing page is developer.twitter.com/en/docs

The link for “Filter realtime tweets” leads to developer.twitter.com/en/docs/tweets/filter-realtime/overview.

But actually, there’s two other streaming tweet endpoints, the user and site endpoints that aren’t documented here, but are documented at “Subscribe to your account activity” (developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/overview). Oh, by the way, those live under Accounts and users, not the Tweets menu on the left. Also, the Guides under this subheading don’t talk about these two endpoints at all. Reference pages don’t seem to link back to guides at all, so if I want a “softer” view than a reference, I have to guess from guide title and click thru.

Furthermore, Subscribe to your account activity talks about the User and Site stream APIs, but contains no links – as a first timer, I thought maybe those were the statuses/filter endpoint, but it’s not, it’s under (same section) API Reference -> GET site / GET user. I understand now that these live under two different contexts – operating with a user’s auth token or not.

(As an aside, it’s pretty ridiculous that statuses/filter apparently doesn’t support the with parameter, but if I create a user and follow someone else, I can then limit to only their tweets (not tweets that mention them).)

Okay, so GET user (developer.twitter.com/en/docs/accounts-and-users/subscribe-account-activity/api-reference/user-stream) is ridiculously underdocumented. There’s a one-liner description:

Streams messages for a single user.

And there’s parameter descriptions. There’s no link to the tweet object (developer.twitter.com/en/docs/tweets/data-dictionary/overview/tweet-object), which is – at least – what my client (twit) feeds me. There’s no link back to how streaming endpoints work (if I were building a client) – actually, there is, but see below, it’s because it’s an erroneous link.

Streaming endpoint references are not differentiated in any meaningful way from non-streaming endpoints, aside from using the word “streaming”, even though they operate (presumably) differently.

The links on the GET user and GET site parameters are broken. Clicking, for example, Seewith(developer.twitter.com/en/docs/tutorials/consuming-streaming-data#with) for more information takes me to “Consuming streaming data”, but guess what, that document doesn’t describe with, or any of the other parameters. This is also true for POST statuses/filter (developer.twitter.com/en/docs/tweets/filter-realtime/api-reference/post-statuses-filter).

Those parameters are actually described on this page (developer.twitter.com/en/docs/tweets/filter-realtime/guides/basic-stream-parameters), which is filed as a “guide”, except not really, since it’s a dang reference page for filter parameters. It also took me another ten minutes, just now, to find this page again. Formatting of code samples on this page is also broken.

I wasn’t able to actually use the site endpoint (“User not in role”), but the reference page gives me no clue as to why (twit also ended up eating the error deep in its internals, leading to an hour of debugging, but that’s their issue, not yours), because the description is a single line.

The link for ...using a Streaming API instead, on the Search API (developer.twitter.com/en/docs/tweets/rules-and-filtering/guides/how-to-build-a-query) page is broken, and goes to a staging page: aem-author-staging.twitter.biz/streaming/overview.html. Actually, maybe all of the links on that page do? I just discovered that while trying to track down other disparate bits of documentation.

On “Intro to Tweet JSON” (developer.twitter.com/en/docs/tweets/data-dictionary/overview/intro-to-tweet-json), I get console errors (“Refused to execute inline script”) and the menu sidebar is broken.

Lastly, I also noticed while writing this post that the sidebar link for Media -> Access Media, which leads to developer.twitter.com/en/docs/tweets/data-dictionary/overview/entities-object1 is 404 broken.


Overall, using the API documentation was an exercise in futility and what almost felt like malign intent. The rest of this is speaking from my personal opinion, but what I see:

In an immediate sense, it needs at a minimum a quality-control pass in your CI/CD to ensure links (including anchors) aren’t broken.

On a broader view, it needs a massive information-architecture overhaul (maybe it just got this? but it’s not working). By organizing into “I want to do” guides ala the Django docs, in a linear, constructive way, with a strict “Reference” section the experience would be far superior. Also, I should never have to go back to a guide from a reference page to learn about parameters or object structures, only to clarify how I might wire things together.

Documentation, in my opinion, should be structured the way developers think. A lot of us think in terms of nouns (“types of objects”) and verbs (“what can I do with/how can I access these objects”). The menu structure and navigation is currently all written in “guide” or soft form, none of it in noun/verb form. There is no list of API endpoints (verbs) from which I can choose the one I know I’m thinking about. I have to navigate a two level menu structure, and then click “API reference” on each subsection to maybe find my endpoint.

For instance, just now: I know I’m looking for a “tweet” object type. In most documentation it would be something like “Docs -> Reference -> tweet object”. Here was my process trying to figure out how to access it just now:

“Tweets” -> “Post retrieve filter …” -> uh… no link for tweets in Overview. Click “Guides”. No, not there either. Hmm. Look on sidebar again. Maybe… “Tweet data dictionaries” (next to other headings, like “Tweet compliance” and “Tweet updates”, it’s very easy to scan right over this heading). Is that the same thing as a tweet object? Ah, okay, here’s actually the reference for tweets, users, entities and extended entities. Why does the sidebar say “data dictionaries”, and not “objects”, when the landing page says “objects”? Why does the documentation refer to them both interchangeably? What on earth is going on?

Lastly, and maybe this is just personal preference, but: I’m not reading a Medium article. I’m not going to navigate away if there’s not an interesting pull-quote and silly GIFs. I’m trying to build something, so I’m reading reference documentation. I don’t need 48px (most pages) or 78px headers (!!!) (tutorial pages) and massive padding. I need to scan vast amounts of highly structured information quickly, which means I need to see a lot of it at the same time.

In short, this documentation is utterly unlike any other dev documentation, in a very negative way. Please, please fix.