Grammar and formatting

Author: dobooth

docs/custom-helpers.md

@@ -1,33 +1,34 @@
 # Custom Helpers
 
-<div class="bs-callout bs-callout-warning" markdown="1">
-Due to complexity, you should only write new Custom Helpers as a last resort after trying to implement your test using built-in actions.
+<div class="bs-callout-warning">
+Due to complexity, you should only write new custom helpers as a last resort, after trying to implement your test using built-in actions.
 </div>
 
-Custom Helpers allow test writers to write custom test actions to solve for advanced requirements beyond what MFTF offers out of the box.
+Custom Helpers allow test writers to write custom test actions to solve advanced requirements beyond what MFTF offers out of the box.
 
-In MFTF version 3.0.0, we removed the following test actions:
+In MFTF version 3.0.0, the following test actions were removed:
 
-* `<executeInSelenium>`
-* `<performOn>`
+*  `<executeInSelenium>`
+*  `<performOn>`
 
 These actions were removed because they allowed custom PHP code to be written inline inside of XML files. This code was difficult to read. It had no proper syntax highlighting and no linting. It was difficult to maintain, troubleshoot, and modify.
 
 However, sometimes custom logic beyond what MFTF offers is necessary so we have provided an alternative solution: the `<helper>` action.
 
 ## Example
 
-Custom Helpers are implemented in PHP files that must be placed in this directory:
-```
+Custom helpers are implemented in PHP files that must be placed in this directory:
+
+```text
 <ModuleName>/Test/Mftf/Helper
 ```
 
-Let's take a look at one. This Custom Helper selects text on the page by this approach:
+This custom helper selects text on the page with this approach:
 
-1. Move to a very specific X,Y starting position
-2. Click and hold the mouse button down
-3. Move to another specific X,Y position
-4. Release the mouse button
+1. Move to a very specific X,Y starting position.
+1. Click and hold the mouse button down.
+1. Move to another specific X,Y position.
+1. Release the mouse button.
 
 This functionality is used to select text on the page and cannot be accomplished using built-in test actions.
 
@@ -79,20 +80,21 @@ class SelectText extends Helper
 }
 ```
 
-### Notes About The PHP File
+### Notes about this PHP file
+
+The following details are important about the above file:
 
-The following details are important about the file above:
-1. The `namespace` must match the file location like `namespace Magento\PageBuilder\Test\Mftf\Helper;`
-2. The class must `extends Helper` and have the corresponding `use` statement to match
-3. You can get access to the WebDriver object via `$this->getModule('\Magento\FunctionalTestingFramework\Module\MagentoWebDriver')`
-4. You can implement multiple related methods in the same class.
-5. Specify the correct function argument types to match the types of the values you want to pass in. In this case we specified `string $context, int $startX, int $startY, int $endX, int $endY` so in the XML we will match these types.
+1. The `namespace` must match the file location: `namespace Magento\PageBuilder\Test\Mftf\Helper;`
+2. The class must `extends Helper` and have the corresponding `use` statement to match.
+3. You may access the WebDriver object via `$this->getModule('\Magento\FunctionalTestingFramework\Module\MagentoWebDriver')`.
+4. You may implement multiple related methods within the same class.
+5. Specify the correct function argument types to match the type of values you want to pass in. In this case, we specified `string $context, int $startX, int $startY, int $endX, int $endY`. In the XML we will match these types.
 
-You should follow the same patterns in any Custom Helpers that you write yourself. But you can implement any logic or iteration that you need to solve for your use case.
+You should follow the same patterns in any custom helpers that you write yourself, but you may implement any logic or iteration that you need to solve for your use case.
 
-### Referencing In A Test
+### Referencing in a test
 
-Once you have implemented something like the above PHP file. You can then reference it in a test like this:
+Once you have implemented something like the above PHP file, reference it in a test:
 
 ```xml
 <helper class="\Magento\PageBuilder\Test\Mftf\Helper\SelectText" method="selectText" stepKey="selectHeadingTextInTinyMCE">
@@ -104,23 +106,23 @@ Once you have implemented something like the above PHP file. You can then refere
 </helper>
 ```
 
-### Notes About The XML
+### Notes about the XML
 
 1. Specify an argument value for every argument that matches our PHP implementation. This allows us to pass other test data to the Custom Helper.
-2. The `class` attribute matches the namespace we specified in the PHP file
-3. You can specify the method from the class via the `method` attribute
-4. If the function has a return value, it will be assigned to the stepKey variable. In this case `$selectHeadingTextInTinyMCE` would hold the return value.
+2. The `class` attribute matches the namespace specified in the PHP file.
+3. Specify the method from the class via the `method` attribute.
+4. If the function has a return value, it will be assigned to the `stepKey` variable. In this case, `$selectHeadingTextInTinyMCE` holds the return value.
 5. The types of argument values must match the PHP implementation's expected types.
 
-## Key Takeaways
+## Key takeaways
 
-Custom Helpers allow you to solve for complex use cases such as conditional logic, iteration, or complex WebDriver usage.
+Custom helpers allow you to solve complex use cases such as conditional logic, iteration, or complex WebDriver usage.
 
 With access to the WebDriver object, you have a lot of flexibility available to you. See the [Codeception WebDriver](https://github.com/Codeception/module-webdriver/blob/master/src/Codeception/Module/WebDriver.php) for technical details and functionality available for use.
 
-A Custom Helper is written in a PHP file and then referenced in test XML like other actions.
+A custom helper is written in a PHP file and then referenced in test XML, like other actions.
 
-Due to complexity, you should only use these as a last resort after trying to implement your test using built-in actions.
+You should only use these as a last resort after trying to implement your test using built-in actions.
 
 ## References