search

twitch4j / twitch4j.github.io

Twitch4J Page
http://twitch4j.github.io
MIT License
4 stars 14 forks source link

Documentation issues #12

Open tedyoung opened 5 years ago

tedyoung commented 5 years ago

I'd like to help improve the docs (at least), so if you're interested in Doc PRs, let me know.

The documentation is confusing in a number of areas, especially when it reads like text has been copied-and-pasted from Twitch's docs. For example, from the Twitch Chat page:

Twitch Chat (WebSocket)

Twitch offers an IRC interface to our chat functionality. This allows you to, for instance:

Develop bots for your channel.
Connect to a channel’s chat with an IRC client instead of using the Web interface.

While our IRC server generally follows RFC1459, there are several cases where it behaves slightly differently than other IRC servers; as described below, there are many Twitch-specific IRC capabilities

This made no sense to me when I was just starting out, so perhaps writing it in terms of the user of this library would be useful?

The "Standalone" vs. "Use as part of Twitch4J" is also confusing. Why would I want to do one or the other?

Finally, the OAuth Token requirement was very confusing and for hours I struggled trying to get the Chat API to work, only to find out that I had the wrong type of OAuth Token. Making it clear which token is needed, and more strongly suggesting to use the https://twitchtokengenerator.com/ site would have saved me lots of frustration.

PhilippHeuer commented 5 years ago

Thats true, i copied sections of the twitch docs partially for the introduction of the modules - i didn't catch that wording then ;) PR's to improve the docs are more than welcome. /docs/content

All 3 points you made are valid and should be improved as it helps new users getting started easier. Thanks for opening the issue.

eltmon commented 2 years ago

I submitted a PR to improve a simple documentation code block oversight on the Getting Started page but it was closed for an invalid reason, so I filed a bug about the page instead.