-
Notifications
You must be signed in to change notification settings - Fork 758
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Link to rationales? #74
Comments
👍 |
@ljharb I love the |
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 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. |
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 |
I gummy bear 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 |
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:
Clicking
|
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 |
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?
The text was updated successfully, but these errors were encountered: