[Concept]: Basic various improvments (#623)

* Refactor instructions and introduction.md

* Fix

* Update method argument syntax

concepts/basics/about.md

@@ -13,16 +13,16 @@ These are some of the language's goals:
 
 - Compile to efficient native code.
 
-The work on Crystal started in 2011 with the goal of creating a language with the elegance and productivity of Ruby, but with the performance and type safety of a compiled language.
-Originally, the language compiler was written in Ruby, but in 2013, the compiler was rewritten in Crystal itself.
-The language was developed and designed by Ary Borenszweig, Juan Wajnerman, Brian Cardif.
+The work on Crystal started in 2011 with the goal of creating a language with the elegance and productivity of Ruby but with the performance and type safety of a compiled language.
+The language compiler was initially written in Ruby, but it was rewritten in Crystal in 2013.
+Ary Borenszweig, Juan Wajnerman, and Brian Cardiff developed and designed the language.
 
 ## Getting Started
 
 ### Variables
 
-To declare a [variable][variables], you must use the `=` assignment operator.
-In Crystal variables should be written in [snake_case][snake-case].
+To declare a [variable][variables], use the `=` assignment operator.
+In Crystal, variables should use [snake_case][snake-case] format.
 
 ```crystal
 number = 1
@@ -34,14 +34,14 @@ puts number # => 2
 
 ### Constants
 
-[Constants][constants] are declared using the same `=` assignment operator, but use all uppercase letters, also known as SCREAMING_SNAKE_CASE.
+[Constants][constants] are declared using the same `=` assignment operator but use all uppercase letters known as SCREAMING_SNAKE_CASE.
 
 ```crystal
 NUMBER = 1
 puts NUMBER # => 1
 ```
 
-Assigning a value to a constant that is already defined will result in a compile-time error.
+Assigning a value to an already defined constant will result in a compile-time error.
 
 ```crystal
 NUMBER = 1
@@ -52,19 +52,19 @@ NUMBER = 2
 
 ### Types
 
-Crystal is a compiled language, which means that every variable or method argument is assigned a type at compile time.
+Crystal is a compiled language, meaing every variable or method argument is assigned a type at compile time.
 The compiler is capable of inferring the type of a variable or method argument.
-Although in some cases it is necessary to specify the type.
-The cases that requires a type to be set will be explained in later concepts.
+However, in some cases, it is necessary to specify the type.
+The cases that require a type to be set will be explained in later concepts.
 
 ### Methods
 
-[Methods][methods] are a way to group together a set of instructions that can be reused.
-In Crystal methods are often defined in a class, module or struct.
-But methods can also be defined outside of a class, module or struct.
-Methods are declared using the `def` keyword, followed by the name of the method.
-In Crystal methods should be written in snake_case.
-When a method doesn't have any arguments, you can omit the parentheses.
+[Methods][methods] are a way to group a set of instructions that can be reused.
+In Crystal, methods are often defined in a class, module, or struct.
+However, methods can also be defined outside of a class, module, or structure.
+Methods are declared using the `def` keyword, followed by the method's name.
+In Crystal, methods should be written in snake_case.
+You can omit the parentheses when a method doesn't have any arguments.
 To declare the end of a method, you must use the `end` keyword.
 
 ```crystal
@@ -73,28 +73,21 @@ def hello
 end
 ```
 
-Using a method that doesn't exist on the type of the variable or method argument will result in a compile-time error.
+Using a method that doesn't exist for the type of variable or method argument will result in a compile-time error.
 
 ```crystal
 number = 1
 number + "1"
-```
-
-```console
-In test.cr:2:7
-
- 2 | number + "1"
-           ^
-Error: no overload matches 'Int32#+' with type String
+# Error: no overload matches 'Int32#+' with type String
 ```
 
 ### Arguments
 
 Methods can have [arguments][arguments].
 Arguments are data that is passed to a method.
 To be able to give a method arguments, you must specify the name of the argument.
-In Crystal arguments should be written in snake_case.
-A method can have multiple arguments, but the arguments must be separated by a comma.
+In Crystal, arguments should be written in snake_case.
+A method can have multiple arguments, but a comma must separate the arguments.
 
 ```crystal
 def hello(name)
@@ -113,12 +106,12 @@ end
 
 ### Calling Methods
 
-When calling a method that belongs to a class, module or struct, you must use the dot operator(`.`).
-Like following: `<ClassName>.<method_name>`.
-When the method doesn't belong to a class, module or struct, then you can simple call it by writing its name.
-Methods always implicitly return the value of the last expression in the method.
+When calling a method that belongs to a class, module, or struct, you must use the dot operator(`.`).
+The format should be: `<ClassName>.<method_name>`.
+When a method doesn't belong to a class, module, or struct, you can simply call it by writing its name.
+Methods always implicitly return the value of the last expression.
 
-When a method has arguments, you may use parentheses when specifying the arguments in the method call and definition, like following: `<method_name>(<argument_1>, <argument_2>)`.
+When a method has arguments, you may use parentheses when specifying the arguments in the method call and definition, like the following: `<method_name>(<argument_1>, <argument_2>, ...)`.
 When a method has no arguments, parentheses should be omitted.
 
 ```crystal
@@ -130,12 +123,12 @@ hello("Crystal")
 # => Hello Crystal!
 ```
 
-When calling a method with multiple arguments, the arguments should be separated by a comma.
+When calling a method with multiple arguments, a comma should separate the arguments.
 The arguments must be given in the same order as the method arguments.
 
 ```crystal
 def hello_language(name, language)
-  puts "Hello #{name}! You are learning #{language}."
+  "Hello #{name}! You are learning #{language}."
 end
 
 hello_language("World", "Crystal")
@@ -146,14 +139,7 @@ Calling a method with the wrong number of arguments will result in a compile-tim
 
 ```crystal
 hello_language("Crystal")
-```
-
-```console
-In test.cr:1:1
-
- 1 | hello_language("Crystal")
-     ^----
-Error: wrong number of arguments for 'hello_language' (given 1, expected 2)
+# wrong number of arguments for 'hello_language' (given 1, expected 2)
 ```
 
 ### Addition & Subtraction & Multiplication
@@ -175,9 +161,9 @@ And you can use the `*` operator to multiply two numbers.
 
 ### Comments
 
-In Crystal [comments][comments] are written with the `#` character, followed by a space and then the comment.
+In Crystal, [comments][comments] are written with the `#` character, followed by a space and then the comment.
 Comments are used to document code.
-Comments are not executed by the compiler.
+The compiler does not execute comments.
 
 ```crystal
 # This is a comment

concepts/basics/introduction.md

@@ -4,8 +4,8 @@
 
 ### Variables
 
-To declare a [variable][variables], you must use the `=` assignment operator.
-In Crystal variables should be written in [snake_case][snake-case].
+To declare a [variable][variables], use the `=` assignment operator.
+In Crystal, variables should use [snake_case][snake-case] format.
 
 ```crystal
 number = 1
@@ -17,14 +17,14 @@ puts number # => 2
 
 ### Constants
 
-[Constants][constants] are declared using the same `=` assignment operator, but use all uppercase letters, also known as SCREAMING_SNAKE_CASE.
+[Constants][constants] are declared using the same `=` assignment operator but use all uppercase letters known as SCREAMING_SNAKE_CASE.
 
 ```crystal
 NUMBER = 1
 puts NUMBER # => 1
 ```
 
-Assigning a value to a constant that is already defined will result in a compile-time error.
+Assigning a value to an already defined constant will result in a compile-time error.
 
 ```crystal
 NUMBER = 1
@@ -35,19 +35,19 @@ NUMBER = 2
 
 ### Types
 
-Crystal is a compiled language, which means that every variable or method argument is assigned a type at compile time.
+Crystal is a compiled language, meaing every variable or method argument is assigned a type at compile time.
 The compiler is capable of inferring the type of a variable or method argument.
-Although in some cases it is necessary to specify the type.
-The cases that requires a type to be set will be explained in later concepts.
+However, in some cases, it is necessary to specify the type.
+The cases that require a type to be set will be explained in later concepts.
 
 ### Methods
 
-[Methods][methods] are a way to group together a set of instructions that can be reused.
-In Crystal methods are often defined in a class, module or struct.
-But methods can also be defined outside of a class, module or struct.
-Methods are declared using the `def` keyword, followed by the name of the method.
-In Crystal methods should be written in snake_case.
-When a method doesn't have any arguments, you can omit the parentheses.
+[Methods][methods] are a way to group a set of instructions that can be reused.
+In Crystal, methods are often defined in a class, module, or struct.
+However, methods can also be defined outside of a class, module, or structure.
+Methods are declared using the `def` keyword, followed by the method's name.
+In Crystal, methods should be written in snake_case.
+You can omit the parentheses when a method doesn't have any arguments.
 To declare the end of a method, you must use the `end` keyword.
 
 ```crystal
@@ -56,28 +56,21 @@ def hello
 end
 ```
 
-Using a method that doesn't exist on the type of the variable or method argument will result in a compile-time error.
+Using a method that doesn't exist for the type of variable or method argument will result in a compile-time error.
 
 ```crystal
 number = 1
 number + "1"
-```
-
-```console
-In test.cr:2:7
-
- 2 | number + "1"
-           ^
-Error: no overload matches 'Int32#+' with type String
+# Error: no overload matches 'Int32#+' with type String
 ```
 
 ### Arguments
 
 Methods can have [arguments][arguments].
 Arguments are data that is passed to a method.
 To be able to give a method arguments, you must specify the name of the argument.
-In Crystal arguments should be written in snake_case.
-A method can have multiple arguments, but the arguments must be separated by a comma.
+In Crystal, arguments should be written in snake_case.
+A method can have multiple arguments, but a comma must separate the arguments.
 
 ```crystal
 def hello(name)
@@ -96,12 +89,12 @@ end
 
 ### Calling Methods
 
-When calling a method that belongs to a class, module or struct, you must use the dot operator(`.`).
-Like following: `<ClassName>.<method_name>`.
-When the method doesn't belong to a class, module or struct, then you can simple call it by writing its name.
-Methods always implicitly return the value of the last expression in the method.
+When calling a method that belongs to a class, module, or struct, you must use the dot operator(`.`).
+The format should be: `<ClassName>.<method_name>`.
+When a method doesn't belong to a class, module, or struct, you can simply call it by writing its name.
+Methods always implicitly return the value of the last expression.
 
-When a method has arguments, you may use parentheses when specifying the arguments in the method call and definition, like following: `<method_name>(<argument_1>, <argument_2>)`.
+When a method has arguments, you may use parentheses when specifying the arguments in the method call and definition, like the following: `<method_name>(<argument_1>, <argument_2>, ...)`.
 When a method has no arguments, parentheses should be omitted.
 
 ```crystal
@@ -113,12 +106,12 @@ hello("Crystal")
 # => Hello Crystal!
 ```
 
-When calling a method with multiple arguments, the arguments should be separated by a comma.
+When calling a method with multiple arguments, a comma should separate the arguments.
 The arguments must be given in the same order as the method arguments.
 
 ```crystal
 def hello_language(name, language)
-  puts "Hello #{name}! You are learning #{language}."
+  "Hello #{name}! You are learning #{language}."
 end
 
 hello_language("World", "Crystal")
@@ -129,14 +122,7 @@ Calling a method with the wrong number of arguments will result in a compile-tim
 
 ```crystal
 hello_language("Crystal")
-```
-
-```console
-In test.cr:1:1
-
- 1 | hello_language("Crystal")
-     ^----
-Error: wrong number of arguments for 'hello_language' (given 1, expected 2)
+# wrong number of arguments for 'hello_language' (given 1, expected 2)
 ```
 
 ### Addition & Subtraction & Multiplication
@@ -158,9 +144,9 @@ And you can use the `*` operator to multiply two numbers.
 
 ### Comments
 
-In Crystal [comments][comments] are written with the `#` character, followed by a space and then the comment.
+In Crystal, [comments][comments] are written with the `#` character, followed by a space and then the comment.
 Comments are used to document code.
-Comments are not executed by the compiler.
+The compiler does not execute comments.
 
 ```crystal
 # This is a comment

exercises/concept/arys-amazing-lasagna/.docs/instructions.md

@@ -1,6 +1,6 @@
 # Instructions
 
-In this exercise you're going to write some code to help you cook a brilliant lasagna from your favorite cooking book.
+In this exercise, you'll write code to help you cook a brilliant lasagna from your favorite cookbook.
 
 You have four tasks, all related to the time spent cooking the lasagna.
 
@@ -25,7 +25,7 @@ Lasagna.new.remaining_minutes_in_oven(30)
 
 ## 3. Calculate the preparation time in minutes
 
-Define the `Lasagna#preparation_time_in_minutes` method that takes the number of layers you added to the lasagna as a parameter and returns how many minutes you spent preparing the lasagna, assuming each layer takes you 2 minutes to prepare.
+Define the `Lasagna#preparation_time_in_minutes` method, which takes the number of layers you added to the lasagna as a parameter and returns the number of minutes you spent preparing it, assuming each layer takes 2 minutes to prepare.
 
 ```Crystal
 Lasagna.new.preparation_time_in_minutes(2)
@@ -35,7 +35,7 @@ Lasagna.new.preparation_time_in_minutes(2)
 ## 4. Calculate the total working time in minutes
 
 Define the `Lasagna#total_time_in_minutes` method that takes two named parameters: the `number_of_layers` parameter is the number of layers you added to the lasagna, and the `actual_minutes_in_oven` parameter is the number of minutes the lasagna has been in the oven.
-The method should return how many minutes in total you've worked on cooking the lasagna, which is the sum of the preparation time in minutes, and the time in minutes the lasagna has spent in the oven at the moment.
+The method should return the total number of minutes you've worked on cooking the lasagna, which is the sum of the preparation time in minutes and the time the lasagna has spent in the oven at the moment.
 
 ```Crystal
 number_of_layers = 3