Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Hi @josevalim!
Two things I wanted to bring up. I combined them because I think the last one
is just tangentially related to the first one.
have used more of a step-by-step flow rather than the current flow.
The current docs work for me, but I like to try to listen to "first impression"
feedback when I do get it. I really listen when it is folks new to the
community. So, I thought that a good place to add the step by step version
would be on the README and we could keep the moduledocs as they are as they are
helpful as well.
The second point is below, related to where I added the docs (in the README)
and also somewhat tangential because I'm asking about preferences not only for
this library, but for libraries in general.
READMEs showcasing 20% of the library features that may be responsible for 80%
of the general usage. Saving that extra click to go to the docs/hex/guides is a win.
My experience may be completely anecdotal, that's why I'm reaching out as I
know you have written your fair share of READMEs in the past and may know
something I don't on this subject.
We have Hex to serve moduledocs and guides. Is that where you think libraries
should focus on their examples/usage? What are your thoughts on this "80/20"
README? Here is an example of an 80/20 README in the
wild
I'm interested in your thoughts. Happy to move this discussion elsewhere as
well. Feel free to ping me in ElixirForum, EEF Slack, anywhere.
As usual, feel free to discard the changes here if you want to, no hard
feelings! Thanks for your work! ❤️