Link to rationales?
ljharb opened this issue · comments
Perhaps a nice way to mitigate the concerns of those who want the guide to be approachable by non-rubyists, without compromising the terseness that some value, would be to add an explicit "Rationale" link to each rule/guideline that links to the pull request where it was discussed?
That would avoid readers having to hunt through git history to figure out why a rule exists.
Another alternative would be to make a separate rationales.md document that was a longer version of the guide, and we could deep link into that from the main readme.
Thoughts?
👍
@ljharb I love the rationales.md idea. It is the best of both worlds: concise style guide backed up with rationales. When can we start???
Immediately :-) PRs welcome! :-p
I'm a fan of this, especially if we enable rich linking in the short guide to the specific section in the long guide.
A link to the PR seems like a good, low-cost way to do it. I like that one.
If you do a separate rationales.md, I think it'll be out of sync a lot. I wouldn't recommend a "long version" of the guide that repeats all the guidelines, either--then it will be even more out of sync.
Since these are style issues, a lot of the time there's no rationale other than "we wanted to pick a style so we picked this one." 😜
we could always of course add an appendix in the main file, then link down to it from the main rule. rationals.md could also be an incomplete list, just existent for linking, rather than an expanded version of the main style guide
Even when the rationale is "the N forms are equivalent and we just like this one better" that's hugely valuable - it informs users which rules they don't have to consider too heavily before deviating from in their own projects.
As long as the rationale is immediately reachable, I will be happy. Requiring users to track down the appropriate PR is super hostile to people not intimately familiar with git/github.
imo this guide shouldn't be primarily or solely aimed at rubyists, it should be aimed at non-rubyists who want to use Ruby (especially newcomers to Ruby that work at Airbnb) - and as such, the rationale is pretty critical to understand as readers are learning the language.
I see two great ideas, a separate file for the rationales and the appendix that @kmsun07 proposed.
As long as "arbitrary consistency" is a valid rationale. I'm not being flippant or sarcastic. For many--I would say most--style rules, that's the reason. Otherwise I would have a hard time justifying, for example, two-space indentation vs. some other number of spaces.
Certainly the only reason to choose any number of spaces for indentation is "arbitrary consistency" 
but sure, that's fine to put as the rationale when that applies.
Will we go with the separate rationales.md file? Or will we go with the appendix? If I had 1 gummy bear to distribute, I would give it to rationales.md. What is everyone feeling? I can start once we all come to a consensus.
I gummy bear rationales.md
I don't think they need to get out of sync - we just make sure people submit PRs that touch both files.
I gummy bear rationales.md
I am getting a sugar high! I will start working on it after a couple more gummies.
gummy bear for rationales.md from me too
I'm reading the style guide again and a lot of the rules are already as short as possible with no rationale. The thing that takes up the most space are the examples. Are we wanting to extract the examples into the rationale?
Checkout this style guide, my absolute favorite: https://github.com/thoughtbot/guides/tree/master/style/ruby
We can do something similar, for example:
- Indent using 2 spaces Example
Clicking Example will take you to the section in the rationales/examples with:
# bad
def foo
1
end
# good
def foo
1
end
Personally, I prefer having the example in the main guide because often the wording of the rule itself isn't clear enough for me to immediately understand what the rule is. By contrast, the rationale is truly optional knowledge.
@tommydangerous My initial reaction was "but the examples are so helpful!"
But then I saw your link to the more concise guide at Thoughtbot and I have to say, I love it. It's so easy to scan. I support your suggestion to move the examples out.
I will create a PR and we can see how it works.
This issue can be closed now, I believe, since rationales.md exists.