Simplify the Readme.

[SerhiiVynohradov]

The first sentence should be a 25-word description of WHAT THIS GEM DOES.

The second sentence may be a 25-word description of HOW IT DOES IT. The big picture.

And only then the rest of Readme (what it integrates with, the options, the settings etc.).

Ideally, it should be a website with a new page for each section.

Request for contributions goes to the bottom.

[zachfeldman]

Hey @zoopyserg , that sounds great! I look forward to your pull request :)

[SerhiiVynohradov]

I already helped you by posting this suggestion.

[lynndylanhurley]

[SerhiiVynohradov]

Yeah, and?
This doesn't answer my question.
As a visitor, I want to know in first 10 seconds, what data gets moved to where, and what for.

[zachfeldman]

Hey @zoopyserg this is a completely volunteer run, not for profit project, so your demanding tone is not helpful.

We appreciate your suggestion but if you want it to get done fast, we'd appreciate your help doing it even more than just opening an issue.

[SerhiiVynohradov]

I think if it's not clear in first few seconds what this project does, the author also doesn't fully understand why he's running this project.

Your task, as a project owner, is to come up with a line that you can tell to a person, absolutely unfamiliar with the jargon, and they would understand it.

The fact that it's non-profit doesn't mean it has to be not understandable.

[SerhiiVynohradov]

Don't expect your users to read everything about everything to understand your project.
Say "The only way to bind front-end frameworks with Devise" as your first line, if that's the case.

[KelseyDH]

This is a constructive blog post on open source documentation that I think all of us could reflect on for how to improve documentation for this gem: https://www.divio.com/en/blog/documentation/

The problem as I see it is there needs to be a clear separation between four concepts as their reasons for existing are very different. They are:

• A tutorial (is learning-oriented)
• How-to guides (is goal-oriented)
• Explanations (are understanding oriented)
• Reference guides (is information oriented)

The current docs are a mix of all four to a various extent. Looking at classic Devise is a good example of how this could be cleaned up, particularly with how Devise has excellent guides on a number of "How-to" items common for many development use cases.

[waiting-for-dev]

@zoopyserg , maybe you feel you have the right to have people out there working for free for you, but open source development is not easy (usually no revenue at all, investing of your free time...). If you don't like something, just don't take it.

The fact that it's non-profit doesn't mean it has to be not understandable.

The fact that is non-profit means that you as a user can't demand anything. They are the maintainers themselves who accept to take a responsibility that technically doesn't exist. Next time you encounter an issue, instead of investing your time to criticize people's work it would more profitable if you solve it. You are wrong if you think that the job of maintaining a project falls backs only in the project owner. Without going any further, this gem has 128 contributors. It would be nice if you became one of them.

[SerhiiVynohradov]

I mean exactly what KelseyDH just said.

There are many great plugins out there.
Too many.
So you have to choose.
The normal way of research looks like "open each one in a new tab, close the ones that don't have demos, are outdated, or are hard to understand from the first sight, and try out the rest".

I came to this gem from several places, so it sounds like if you want tokens for SPA on Rails, this is the way to go.

And when I come here, I don't expect the Readme to start with "Contributors wanted".
I expect the first line to tell me why this gem is the best option.

I'm saying don't be on the way of people trying to learn it.
I don't demand anything.

[zachfeldman]

Hey @waiting-for-dev , we really appreciate your encouraging comments in this situation. Have a great day!

[SerhiiVynohradov]

Say:

Summary
If you're building SPA on Rails, and you want authentication, you need tokens, not cookies.
Tokens need to be refreshed on each claim to keep the app secure and convenient.
You need to expire tokens if the user signs out.
If the user has many devices, there may be many tokens per account, and each one needs to be analyzed separately.
This gem handles all the server-side aspects of this.
On the client-side you may have any framework you like.

DEMOS

• Angular
• Reakt
• jToker
• Vue
  ...

Installation
...

Usage
...

Settings
...

I'm not qualified yet to commit that.
I may be wrong about some of these things.
But that's in a nutshell what I would put on top of my Readme.
Readme should be the place after which I have to look no further.

I find @waiting-for-dev 's docs on devise-jwt much more comprehensive.
Which is the main reason why I tried that gem first, before trying this one.

[lynndylanhurley]

@zoopyserg thank you, that summary is an improvement over mine.

@waiting-for-dev thank you for your kind words.

@KelseyDH thanks for your input. I'll read through that link ASAP.

Re-opening this for further discussion.

[RigoOnRails]

@zoopyserg Wow, you must be a very lovely person to deal with.