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

Add section about official Ruby Language Documentation #3352

Open
wants to merge 1 commit into
base: master
Choose a base branch
from

Conversation

lucianghinda
Copy link

Context

  1. In my experience, not many developers use the docs.ruby-lang.org documentation as their main point of reference about the language, and people occasionally ask what the official documentation is.

For this I think it is good to move the link to the official documentation at the top of the page.

  1. I also discovered that there are people who, when reading API documentation, automatically think about web API and do not consider that API is an Application Programming Interface. When we usethe term here API documentation, we refer to the documentation about how to use the language.

For this, I think it is good to use a wording that says "the Ruby language documentation" instead of "the Ruby API documentation"

Changes

  • Introduce new section highlighting docs.ruby-lang.org as the authoritative source for Ruby language documentation

  • Clarify that this should be the first reference for learning Ruby or when having the need to understand how Ruby works

  • Explain that other resources are complementary or present documentation in different styles

  • Try to help quickly identify the official Ruby language documentation for the reader by removing an acronym and replacing it with an explicit wording

PS: I am not an English speaker, so if anyone can help with better phrasing, please do so.

The purpose of this commit is to:

- Introduce new section highlighting docs.ruby-lang.org as the
  authoritative source for Ruby language documentation

- Clarify that this should be the first reference for learning Ruby or
  when having the need to understand how Ruby works

- Explain that other resources are complementary or present
documentation in different styles

- Try to help quickly identify for the reader what is the official Ruby
  language documentation.
@lucianghinda lucianghinda requested a review from a team as a code owner August 25, 2024 15:21
@@ -52,7 +56,7 @@ the [installation guide](installation/) for help on installing Ruby.
### Reference Documentation

[Official API Documentation][docs-rlo-en]
: The official Ruby API documentation for different versions including
: The official Ruby language documentation for different versions including
the currently unreleased (trunk) version.

[Ruby Core Reference][13]
Copy link
Member

Choose a reason for hiding this comment

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

Both link 13 and 15 are pointing to outdated source on ruby-doc.org: https://ruby-doc.org/3.2.2/, which has the same content as docs.ruby-lang.org. Since they don't serve additional information nor have better UX (IMO), I think we can remove them to shorten the list.

Additionally, link 17 (https://rubydocs.org/) is blank and link 18 (https://apidock.com/) only has documentation up to 2.6. So they should be removed as well.

(I'm happy to open a separate PR to remove them if it's out of the scope of this PR)

Copy link
Member

Choose a reason for hiding this comment

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

I opened #3355 to remove them.

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.

2 participants