tl;dr: Uniformly formatted, concise documentation makes developers more productive. Thanks for your consideration.
Wall-of-text version:
Some of the API documentation is, to be frank, pretty scattered, verbose, indirect, and difficult to use. Often it reads more like a tutorial blog than an API documentation. I’m not saying there’s no place for this- but I think it’s wrong for the quality of the API documentation to suffer because of it. Sometimes I need to dig through a big hunk of English-language text to figure out something that should be straightforward to document without prose, like whether to put a value in a header, body, or query string. HTTP methods should be mostly documentable in a standard table format with a few items, maybe with a short section on edge-cases or strange behavior (but not interlaced with the actual table items).
For example, if I visit the refresh token doc section it just offhandedly mentions in the middle of an opening sentence that the parameters are supposed to be in the request body-- without explaining what the request format should be first. Then to specify the actual request format, several paragraphs later, it gives a CURL command. I’ve seen this in multiple places so far, and had to look up the CURL implementation to be sure I was translating its arguments correctly into HTTP requests. To me this is pretty silly since it should be pretty easy to specify an HTTP request and building a Twitch application should not require CURL expertise as a prerequisite. All I need to know are what the endpoint is, what HTTP method it’s using, what goes in the headers, what goes in the body, and what goes in the query string (and maybe even a link to the longer-form documentation to answer any FAQs about pathological endpoints). I will choose CURL or some other HTTP request utility as my project needs direct.
Please offer a concise API doc with actual HTTP request/response specs. When I say concise, I mean once I reach the appropriate documentation section I should be able to gleam what I need in 10-15 seconds by scanning to the right heading (for example I could figure out the required headers by scrolling to “Required Headers”). Everything should be encapsulated so that I can, as a credentialed app developer, find everything I need to make a request to some endpoint by just visiting its doc page.
