From b0743dda8c0073df240907caf4e684b27cf13a39 Mon Sep 17 00:00:00 2001 From: Kevin Jacoby Date: Thu, 12 Dec 2019 19:43:51 +0000 Subject: [PATCH] Clarify documentation by removing charged words Using words such as 'just', 'simply' and 'easy' implies to the reader that the tasks they are trying to accomplish are tasks that anyone can do, which might then frustrate them if they find it difficult to complete. This commit rephrases some usage of these words to aid understanding in the readers without making them feel belittled. [ci skip] --- guides/source/active_record_basics.md | 3 +-- guides/source/active_record_callbacks.md | 2 +- guides/source/active_record_migrations.md | 13 ++++++------- guides/source/active_record_validations.md | 17 ++++++++--------- guides/source/association_basics.md | 6 +++--- guides/source/contributing_to_ruby_on_rails.md | 4 ++-- 6 files changed, 21 insertions(+), 24 deletions(-) diff --git a/guides/source/active_record_basics.md b/guides/source/active_record_basics.md index d765e32ac74..4cd0589035e 100644 --- a/guides/source/active_record_basics.md +++ b/guides/source/active_record_basics.md @@ -133,8 +133,7 @@ NOTE: While these column names are optional, they are in fact reserved by Active Creating Active Record Models ----------------------------- -It is very easy to create Active Record models. All you have to do is to -subclass the `ApplicationRecord` class and you're good to go: +To create Active Record models, subclass the `ApplicationRecord` class and you're good to go: ```ruby class Product < ApplicationRecord diff --git a/guides/source/active_record_callbacks.md b/guides/source/active_record_callbacks.md index 617f81d37b5..1518c704ff4 100644 --- a/guides/source/active_record_callbacks.md +++ b/guides/source/active_record_callbacks.md @@ -354,7 +354,7 @@ The callback only runs when all the `:if` conditions and none of the `:unless` c Callback Classes ---------------- -Sometimes the callback methods that you'll write will be useful enough to be reused by other models. Active Record makes it possible to create classes that encapsulate the callback methods, so it becomes very easy to reuse them. +Sometimes the callback methods that you'll write will be useful enough to be reused by other models. Active Record makes it possible to create classes that encapsulate the callback methods, so they can be reused. Here's an example where we create a class with an `after_destroy` callback for a `PictureFile` model: diff --git a/guides/source/active_record_migrations.md b/guides/source/active_record_migrations.md index 9398244ccf3..49bcdab9601 100644 --- a/guides/source/active_record_migrations.md +++ b/guides/source/active_record_migrations.md @@ -5,8 +5,7 @@ Active Record Migrations Migrations are a feature of Active Record that allows you to evolve your database schema over time. Rather than write schema modifications in pure SQL, -migrations allow you to use an easy Ruby DSL to describe changes to your -tables. +migrations allow you to use a Ruby DSL to describe changes to your tables. After reading this guide, you will know: @@ -22,7 +21,7 @@ Migration Overview Migrations are a convenient way to [alter your database schema over time](https://en.wikipedia.org/wiki/Schema_migration) -in a consistent and easy way. They use a Ruby DSL so that you don't have to +in a consistent way. They use a Ruby DSL so that you don't have to write SQL by hand, allowing your schema and changes to be database independent. You can think of each migration as being a new 'version' of the database. A @@ -497,7 +496,7 @@ NOTE: Active Record only supports single column foreign keys. `execute` and `structure.sql` are required to use composite foreign keys. See [Schema Dumping and You](#schema-dumping-and-you). -Removing a foreign key is easy as well: +Foreign keys can also be removed: ```ruby # let Active Record figure out the column name @@ -789,7 +788,7 @@ $ rails db:migrate:redo STEP=3 ``` Neither of these rails commands do anything you could not do with `db:migrate`. They -are simply more convenient, since you do not need to explicitly specify the +are there for convenience, since you do not need to explicitly specify the version to migrate to. ### Setup the Database @@ -1036,9 +1035,9 @@ end ``` To add initial data after a database is created, Rails has a built-in -'seeds' feature that makes the process quick and easy. This is especially +'seeds' feature that speeds up the process. This is especially useful when reloading the database frequently in development and test environments. -It's easy to get started with this feature: just fill up `db/seeds.rb` with some +To get started with this feature, fill up `db/seeds.rb` with some Ruby code, and run `rails db:seed`: ```ruby diff --git a/guides/source/active_record_validations.md b/guides/source/active_record_validations.md index fbb776c1609..e613b4116ef 100644 --- a/guides/source/active_record_validations.md +++ b/guides/source/active_record_validations.md @@ -42,9 +42,8 @@ database. For example, it may be important to your application to ensure that every user provides a valid email address and mailing address. Model-level validations are the best way to ensure that only valid data is saved into your database. They are database agnostic, cannot be bypassed by end users, and are -convenient to test and maintain. Rails makes them easy to use, provides -built-in helpers for common needs, and allows you to create your own validation -methods as well. +convenient to test and maintain. Rails provides built-in helpers for common +needs, and allows you to create your own validation methods as well. There are several other ways to validate data before it is saved into your database, including native database constraints, client-side validations and @@ -77,7 +76,7 @@ example using the `new` method, that object does not belong to the database yet. Once you call `save` upon that object it will be saved into the appropriate database table. Active Record uses the `new_record?` instance method to determine whether an object is already in the database or not. -Consider the following simple Active Record class: +Consider the following Active Record class: ```ruby class Person < ApplicationRecord @@ -123,7 +122,7 @@ database only if the object is valid: The bang versions (e.g. `save!`) raise an exception if the record is invalid. The non-bang versions don't: `save` and `update` return `false`, and -`create` just returns the object. +`create` returns the object. ### Skipping Validations @@ -204,7 +203,7 @@ end # => ActiveRecord::RecordInvalid: Validation failed: Name can't be blank ``` -`invalid?` is simply the inverse of `valid?`. It triggers your validations, +`invalid?` is the inverse of `valid?`. It triggers your validations, returning true if any errors were found in the object, and false otherwise. ### `errors[]` @@ -307,7 +306,7 @@ end This validation is very specific to web applications and this 'acceptance' does not need to be recorded anywhere in your database. If you -don't have a field for it, the helper will just create a virtual attribute. If +don't have a field for it, the helper will create a virtual attribute. If the field does exist in your database, the `accept` option must be set to or include `true` or else the validation will not run. @@ -1198,7 +1197,7 @@ validator type. ### `errors[:base]` -You can add error messages that are related to the object's state as a whole, instead of being related to a specific attribute. You can use this method when you want to say that the object is invalid, no matter the values of its attributes. Since `errors[:base]` is an array, you can simply add a string to it and it will be used as an error message. +You can add error messages that are related to the object's state as a whole, instead of being related to a specific attribute. You can use this method when you want to say that the object is invalid, no matter the values of its attributes. Since `errors[:base]` is an array, you can add a string to it and it will be used as an error message. ```ruby class Person < ApplicationRecord @@ -1259,7 +1258,7 @@ validations fail. Because every application handles this kind of thing differently, Rails does not include any view helpers to help you generate these messages directly. However, due to the rich number of methods Rails gives you to interact with -validations in general, it's fairly easy to build your own. In addition, when +validations in general, you can build your own. In addition, when generating a scaffold, Rails will put some ERB into the `_form.html.erb` that it generates that displays the full list of errors on that model. diff --git a/guides/source/association_basics.md b/guides/source/association_basics.md index 27387ac3aca..26aaab02caa 100644 --- a/guides/source/association_basics.md +++ b/guides/source/association_basics.md @@ -406,7 +406,7 @@ NOTE: Using `t.bigint :supplier_id` makes the foreign key naming obvious and exp ### Choosing Between `has_many :through` and `has_and_belongs_to_many` -Rails offers two different ways to declare a many-to-many relationship between models. The simpler way is to use `has_and_belongs_to_many`, which allows you to make the association directly: +Rails offers two different ways to declare a many-to-many relationship between models. The first way is to use `has_and_belongs_to_many`, which allows you to make the association directly: ```ruby class Assembly < ApplicationRecord @@ -2459,7 +2459,7 @@ Let's say we have Car, Motorcycle, and Bicycle models. We will want to share the `color` and `price` fields and some methods for all of them, but having some specific behavior for each, and separated controllers too. -Rails makes this quite easy. First, let's generate the base Vehicle model: +First, let's generate the base Vehicle model: ```bash $ rails generate model vehicle type:string color:string price:decimal{10.2} @@ -2503,7 +2503,7 @@ will generate the following SQL: INSERT INTO "vehicles" ("type", "color", "price") VALUES ('Car', 'Red', 10000) ``` -Querying car records will just search for vehicles that are cars: +Querying car records will search only for vehicles that are cars: ```ruby Car.all diff --git a/guides/source/contributing_to_ruby_on_rails.md b/guides/source/contributing_to_ruby_on_rails.md index 40ed9a1d6b7..ce14c153eed 100644 --- a/guides/source/contributing_to_ruby_on_rails.md +++ b/guides/source/contributing_to_ruby_on_rails.md @@ -48,9 +48,9 @@ Having a way to reproduce your issue will be very helpful for others to help con These templates include the boilerplate code to set up a test case against either a released version of Rails (`*_gem.rb`) or edge Rails (`*_master.rb`). -Simply copy the content of the appropriate template into a `.rb` file and make the necessary changes to demonstrate the issue. You can execute it by running `ruby the_file.rb` in your terminal. If all goes well, you should see your test case failing. +Copy the content of the appropriate template into a `.rb` file and make the necessary changes to demonstrate the issue. You can execute it by running `ruby the_file.rb` in your terminal. If all goes well, you should see your test case failing. -You can then share your executable test case as a [gist](https://gist.github.com), or simply paste the content into the issue description. +You can then share your executable test case as a [gist](https://gist.github.com), or paste the content into the issue description. ### Special Treatment for Security Issues