Skip to content
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

Merged
merged 1 commit into from
Dec 31, 2024

Conversation

zenspider
Copy link
Member

@zenspider zenspider commented Nov 20, 2024

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

@zenspider zenspider requested a review from a team as a code owner November 20, 2024 05:43
@zenspider zenspider force-pushed the zenspider/update_docs branch from cbaea65 to bb2fea0 Compare November 20, 2024 05:47
@kaya3
Copy link

kaya3 commented Nov 21, 2024

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.

Copy link
Member

@st0012 st0012 left a 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 🙂

[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
Copy link
Member

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?

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.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Intermediate?

Copy link
Member

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]
Copy link
Member

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.

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.

Copy link
Member Author

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

Comment on lines 158 to 159
All of these editors support the Language Server Protocol (LSP). You
can use Shopify's [ruby-lsp][ruby-lsp] plugin for ruby support.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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)

@zenspider
Copy link
Member Author

Pushed some edits based on feedback.

Please let me squash and reword before merge (assuming).

Copy link
Member

@st0012 st0012 left a 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 👍

: The ruby quick reference

[rubyreferences][43]
: A full language reference + detailed language changelog. Fantastic.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Extra spacing:

Suggested change
: 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?

* [Zed][zed]
* Intermediate
* [RubyMine][27] (paid)
* Expert
Copy link
Member

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"?

Suggested change
* Expert
* Difficult

[Airbnb][48]
: AirBNB's Ruby style guide

[w3resource][49]
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for your contribution and for adding helpful links 🙌🏻 I noticed this one has significant number of ads (screenshot below). While the content looks valuable, I wonder if we should consider whether this is a good addition to be on the documentation page on the Ruby official website 🤔

CleanShot 2024-11-25 at 21 51 56@2x

Copy link
Contributor

@andyw8 andyw8 left a 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.

#### Beginner

[Programming Ruby 3.3][pickaxe]
: The seminal work on Ruby in English. Recently updated to ruby 3.3.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
: 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.

#### Intermediate

[Practical OOD in Ruby (POODR)][poodr]
: A programmers tale about how to write object-oriented code.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
: A programmers tale about how to write object-oriented code.
: A programmer's tale about how to write object-oriented code.

: Explains metaprogramming in a down-to-earth style.

[Ruby Under a Microscope (RUM)][microscope]
: An illustrated guide to ruby internals.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
: An illustrated guide to ruby internals.
: An illustrated guide to Ruby internals.

### Style Guides

[rubystyle.guide][44]
: Rubocop's Ruby style guide
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
: Rubocop's Ruby style guide
: RuboCop's Ruby style guide

: Gitlab's Ruby style guide

[Airbnb][48]
: AirBNB's Ruby style guide
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
: AirBNB's Ruby style guide
: Airbnb's Ruby style guide

: AirBNB's Ruby style guide

[w3resource][49]
: W3's Ruby style guide
Copy link
Contributor

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.

: online API documentation

[Ruby QuickRef][42]
: The ruby quick reference
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
: The ruby quick reference
: The Ruby quick reference

Copy link

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.

Comment on lines +194 to +188
[Programming Ruby][9]
: The seminal work on Ruby in English, this first edition of the
[Pragmatic Programmers’ book][10] is available for free online.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
[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.

Copy link
Member Author

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.

@zenspider zenspider force-pushed the zenspider/update_docs branch from 0ebe1b7 to 3d2448f Compare November 27, 2024 04:27

### Further Reading

[Official FAQ](/en/documentation/faq/)
: The official frequently asked questions.

[Ruby-doc.org][34] maintains a comprehensive list of English
Copy link
Member

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.

@zenspider zenspider force-pushed the zenspider/update_docs branch 2 times, most recently from e06176d to a9f70c4 Compare November 27, 2024 21:39
Copy link
Member

@st0012 st0012 left a 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.
@zenspider zenspider force-pushed the zenspider/update_docs branch from a9f70c4 to e4a7db6 Compare December 8, 2024 22:38
Copy link
Contributor

@jeremyevans jeremyevans left a 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
: 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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
: Online code bootcamp with a variety of topics. Freeish.
: Online code bootcamp with a variety of topics.

@JuanitoFatas
Copy link
Member

Do we need to link to six different Ruby style guides 😅?

@st0012
Copy link
Member

st0012 commented Dec 16, 2024

FWIW, I'll be happy to open follow up PRs to address the remaining concerns and further polish the content.

@fiveNinePlusR
Copy link

It feels like it's worth merging and further opening issues for any nits to me.

@jeremyevans jeremyevans merged commit a17c89b into ruby:master Dec 31, 2024
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

Outdated "getting started" links
7 participants