Twitch offers a very large, widely-used API to a very large developer base, and unfortunately the documentation currently provided is severely lacking, inconsistent and falling behind standards of both accessibility and developer experience.

I know this has been proposed some years ago, but I am going to recreate the voice as I believe I can add some extra points and reasoning.

Issues with Accessibility:

• Twitch only offers developers documentation in a fully white (#FFFFFF) background. While this is acceptable for most, this can be extremely difficult to navigate for people with certain eye, neurological and learning conditions. High contrast websites with white or close to white backgrounds have been shown to increase headaches, eye pain and sensitivity, reading and comprehension difficulties in people with these conditions.

• The site offers very little contrast between important or differing sections of various parts of the documentation, for example all the tables, the highlights in the search and code-blocks.

• There are no clear dividers between sections of the documentation, and parts which should be of lesser importance are more visible (bolder/higher contrast) than the sections diving them. E.g. https://dev.twitch.tv/docs/drops/ here under Test The Drop, it's not easily evident which section I am in as the H3 font weight is actually less than the H4, and the list.

• Tables use simple whitespace indentation [which is often inconsistent and hard to read (especially given the above)], when trying to describe inner objects. See below: 1.

Issues with usability:

• There are no admonitions that clearly represent important notes, warnings etc that allow developers to clearly identify focus points.

• 1. Instead of describing inner objects as separate objects we have to try and align indentation which can often lead to mistakes.

• The tables that describe the response objects don't have indicators for nullable or optional fields, or if they do? they are an outlier, and are often wrong, or inconsistently described in the description column.

• The tables are not dynamically sized and just squish and word-break a lot of the fields in bad places making it harder again to read especially when whitespace is used to indicate separate objects. (Check the flag reference here https://dev.twitch.tv/docs/cli/websocket-event-command/, even on a decently sized window.)

• HTTP Methods ("GET", "POST") etc aren't clearly identifiable on endpoints.

• Reference pages can be daunting to navigate, for example https://dev.twitch.tv/docs/eventsub/eventsub-reference/#events there are no inner href or visible references to any of these objects.

• All the feedback buttons and status page are broken.

Why Open Source?
It's clear there is a need for better documentation. It's clear there is a need for developers that use the documentation to be able to express their ideas, issues and make pull-requests in a developer friendly/usable space (Like GitHub) and not community spaces like Discord or User Voices. Creating an Open Source space allows developers to identify changes and bugs as they are made and create relevant issues or pull-requests that can actually reference relevant code. It allows issues, commits, bugfixes etc to be easily tracked and searched. It takes brain power from you and distributes it to us, that's less money on coffee.