How might we make the README provide better guidance to people new to authentication, while being straightforward for people who are familiar with authentication?

[gonzalo-bulnes]

Based on the questions asked in issues and the corresponding answers I see regularly in issues, I think a fair amount of people sue this gem when getting started setting up authentication for a project.

Security is a world of trade-offs and everything "depends" to some extent. However, there are use cases for which I wouldn't use simple_token_authentication for (e.g. long-lived authentication for a web or mobile app). And I think there would be value in providing potential users with some guidance. (I'm convinced that sometimes, the best value for this project can be pointing them to different gems more fitted to their needs.)

Based on my own usage of GitHub and what I've seen in my team, I believe most people only read the README (and often only skim through it). Because of that, I believe that anything important must be in the README.

However, the README is pretty long already as it is, and I think we don't want to get in the way of the people who know exactly what they're looking for an want to learn quickly about the gem's API. Accessibility means to accommodate an range of experience levels as wide as possible in this case.

I don't have clear thoughts on the how, but I'd like to start a conversation about two things:

• what guidance would be most useful to people getting started with authentication? (If any!)
• how might we present it so that it is accessible to the people who need it, and the README stays useful for those who don't need the guidance?

[gonzalo-bulnes]

Similarly: how might we define and communicate the scope of simple_token_authentication in a way that provides a starting point to conversations about new features?

I (obviously) have thoughts on what I think the scope should be at this point for simple_token_authentication, thinking about that is a great portion of what maintaining a project means. However, everything being a trade-off, I'd love to hear your thoughts if you have some : )