Please revert the EventSub documentation format changes
You changed the EventSub documentation between last night (Nov 16, 2021) and today (Nov 17, 2021). The new documentation is very confusing. Specifically speaking:
- The Subscription Types documentation links on the left side are out of order and like-kind events are not next to each other. For example, "Redemption Status Update" should be next to "Channel Points redeem reward".
- The Subscription Types are poor named, and it's a little difficult to figure out which Subscription Type goes to which event.
- The URL to go straight to the section in the Subscription Types is different from the type supplied in an EventSub call. It makes it harder to know I'm going to the right documentation without clicking on the Subscription Type link and reading part of the documentation after I've been redirected to the documentation. For an explicit example, let's say I'm looking for Channel Points Reward Redemption Update documentation (channel.channelpointscustomrewardredemption.update). I first look through the list of Subscription Types and see four "Channel Points" related events, but Channel Points reward redemption update is not there. Instead, it's named "Reward status update" and much further down the list. When I see just 4 of the expected 5 EventSub types on first glance, my initial thought is you've removed an EventSub event type. Upon further inspection, I realized it was just named poorly.
- The old documentation had an EXTREMELY helpful table at the top of the documentation that described the "Category" of EventSub types, "Type" for the specific EventSub event, and a brief note about what that event was notifying about. This table is gone, and now I'm having to click on -EVERY- -SINGLE- -ONE- of the event types in order to figure out what each of those events are for.
- You got rid of the example CURL calls for each of the Subscription Types, which, at a glance, let me know EXACTLY what needed to be included in a request for that specific Subscription Type.
- You got rid of the example payloads for each of the Subscription Type calls, so now I' have to use no less than THREE different documentation pages to make sure I'm constructing the right payload for each event.
- The old documentation had a table for the Condition parameters for each Subscription Type. The old table was INCREDIBLY helpful because it let me know in an well-formatted way exactly what parameters were mandatory, which were optional, and which conflicted with each other. This paragraph description is basically USELESS and makes it much harder to figure out what I need to do on my end from a programming standpoint.
- The Example Event Data does not include a full response from a successful call, so, once again, I have to go to THREE OR MORE documentation pages to figure out what a response call might look like. Even then I'm not entirely sure it's correct, so I'm left making calls to create EventSub notifications to see if I'm parsing everything correctly. The lack of a FULL response is slowing down my testing and validation that I'm doing things correctly on my end.
I'm done for now, but I'm sure I'll find more stuff that's terrible about this new documentation format.
The documentation for EventSub has been reverted to the previous state. To reiterate @ecressey comment, we appreciate the feedback. We will take another look at how we can achieve the intended goal of the changes that were made without compromising the benefits of the current state and specifically the points you mention.
Adminecressey (Admin, Twitch) commented
Hi OGJunkyard, thank you for reading the docs and taking time to give us feedback. We are looking into your feedback now.