-
Notifications
You must be signed in to change notification settings - Fork 623
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
First pass at updating en/documentation/index.md #3427
Conversation
cbaea65
to
bb2fea0
Compare
From my (new to Ruby) perspective, this looks like a massive improvement. Having just completed the Ruby Koans, I can confirm that they are still correct for Ruby 3.3. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a HUGE improvement ❤️
Just a few suggestions 🙂
en/documentation/index.md
Outdated
[The Well-Grounded Rubyist][grounded] | ||
: A tutorial that begins with your first Ruby program and takes you all the way to sophisticated topics like reflection, threading, and recursion. | ||
|
||
#### Adept |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
As a non-native English speaker, I think Adept
is a relatively rare choice of word. Maybe Advanced
will be more approachable?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Maybe Experienced
would be better? Advanced and Expert are closer in my mind than Adept/Experienced and Expert are.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Intermediate?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Intermediate sounds good to me 👍
* Expert | ||
* [Emacs][20] with [Ruby mode][21] or [Enhanced Ruby mode][enh-ruby-mode] | ||
* [Vim][25] with [vim-ruby][26] plugin | ||
* [NeoVim][neovim] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'm not sure if we need or should pair editors with experience levels. For example, I started writing Ruby with Vim, then switched to NeoVim for like 6 years, and switched to VS Code like 2 years ago.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think the idea is from an approachability standpoint instead of an end user skill level standpoint.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
yeah, I meant this more about learning curve of the editor
en/documentation/index.md
Outdated
All of these editors support the Language Server Protocol (LSP). You | ||
can use Shopify's [ruby-lsp][ruby-lsp] plugin for ruby support. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
All of these editors support the Language Server Protocol (LSP). You | |
can use Shopify's [ruby-lsp][ruby-lsp] plugin for ruby support. | |
All of these editors support the Language Server Protocol (LSP), either by default or through their LSP plugins. | |
Shopify's [ruby-lsp][ruby-lsp] is one of the most popular language servers for Ruby and [supports all of the above editors](https://shopify.github.io/ruby-lsp/editors.html) |
Pushed some edits based on feedback. Please let me squash and reword before merge (assuming). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Left few nitpicks but LGTM 👍
en/documentation/index.md
Outdated
: The ruby quick reference | ||
|
||
[rubyreferences][43] | ||
: A full language reference + detailed language changelog. Fantastic. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Extra spacing:
: A full language reference + detailed language changelog. Fantastic. | |
: A full language reference + detailed language changelog. Fantastic. |
While I agree it's a fantastic work, it feels a bit odd to add Fantastic.
in its description?
en/documentation/index.md
Outdated
* [Zed][zed] | ||
* Intermediate | ||
* [RubyMine][27] (paid) | ||
* Expert |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nit: Maybe "difficult" can fit the tooling context better than "expert"?
* Expert | |
* Difficult |
[Airbnb][48] | ||
: AirBNB's Ruby style guide | ||
|
||
[w3resource][49] |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Thank you for working to improve this.
en/documentation/index.md
Outdated
#### Beginner | ||
|
||
[Programming Ruby 3.3][pickaxe] | ||
: The seminal work on Ruby in English. Recently updated to ruby 3.3. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
: The seminal work on Ruby in English. Recently updated to ruby 3.3. | |
: The seminal work on Ruby in English. Recently updated to Ruby 3.3. |
en/documentation/index.md
Outdated
#### Intermediate | ||
|
||
[Practical OOD in Ruby (POODR)][poodr] | ||
: A programmers tale about how to write object-oriented code. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
: A programmers tale about how to write object-oriented code. | |
: A programmer's tale about how to write object-oriented code. |
en/documentation/index.md
Outdated
: Explains metaprogramming in a down-to-earth style. | ||
|
||
[Ruby Under a Microscope (RUM)][microscope] | ||
: An illustrated guide to ruby internals. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
: An illustrated guide to ruby internals. | |
: An illustrated guide to Ruby internals. |
en/documentation/index.md
Outdated
### Style Guides | ||
|
||
[rubystyle.guide][44] | ||
: Rubocop's Ruby style guide |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
: Rubocop's Ruby style guide | |
: RuboCop's Ruby style guide |
en/documentation/index.md
Outdated
: Gitlab's Ruby style guide | ||
|
||
[Airbnb][48] | ||
: AirBNB's Ruby style guide |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
: AirBNB's Ruby style guide | |
: Airbnb's Ruby style guide |
: AirBNB's Ruby style guide | ||
|
||
[w3resource][49] | ||
: W3's Ruby style guide |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I'd suggest dropping this, it seems to be a copy-paste of Airbnb's guide.
en/documentation/index.md
Outdated
: online API documentation | ||
|
||
[Ruby QuickRef][42] | ||
: The ruby quick reference |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
: The ruby quick reference | |
: The Ruby quick reference |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I would add that this is for both the language and the standard library. Many references for other languages cover just one or the other.
[Programming Ruby][9] | ||
: The seminal work on Ruby in English, this first edition of the | ||
[Pragmatic Programmers’ book][10] is available for free online. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
[Programming Ruby][9] | |
: The seminal work on Ruby in English, this first edition of the | |
[Pragmatic Programmers’ book][10] is available for free online. | |
[Programming Ruby][9] | |
: The first edition of this seminal work on Ruby in English is available for free online. |
The current edition is already linked to in the Books section.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
It is. They are different things.
0ebe1b7
to
3d2448f
Compare
en/documentation/index.md
Outdated
|
||
### Further Reading | ||
|
||
[Official FAQ](/en/documentation/faq/) | ||
: The official frequently asked questions. | ||
|
||
[Ruby-doc.org][34] maintains a comprehensive list of English |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I think this and link 34 can be removed because it's been listed in the Reference Documentation
section and it's not really a "further reading" anyway.
e06176d
to
a9f70c4
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
IMO, we can merge this first and do follow up improvements later.
LOTS of bitrot on this page. Most has been removed but some have been moved down to an "older" section. Added new sections: Manuals / Books, Style Guides, Tools, and revamped the editors section.
a9f70c4
to
e4a7db6
Compare
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I agree, this is a great improvement. I only have a couple minor suggestions to avoid a couple single word sentences.
: The Ruby quick reference | ||
|
||
[rubyreferences][43] | ||
: A full language reference + detailed language changelog. Fantastic. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
: A full language reference + detailed language changelog. Fantastic. | |
: A full language reference + detailed language changelog |
: A free online manual with beginner and intermediate content plus a | ||
thorough language reference. | ||
[Codecademy][codecademy] | ||
: Online code bootcamp with a variety of topics. Freeish. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
: Online code bootcamp with a variety of topics. Freeish. | |
: Online code bootcamp with a variety of topics. |
Do we need to link to six different Ruby style guides 😅? |
FWIW, I'll be happy to open follow up PRs to address the remaining concerns and further polish the content. |
It feels like it's worth merging and further opening issues for any nits to me. |
main changes:
LOTS of bitrot on this page. Most has been removed but some have been
moved down to an "older" section.
Revamped editor section to include difficulty "levels"
Added a bunch of sections and links mostly derived from the ruby
discord's #library.
This fixes #3426