additions to nme-standard branch (#754)

* Use an opinionated set of rules for Rubocop

Most projects that thoughtbot is working on currently did not start here.
The "Use standard" recommendation comes from a time that that wasn't
true.

There are a few reasons not to use Standard in existing projects:
- A large project does not already use Standard and retrofitting would be costly
- Need or want Rubocop rules other than Standard's opinionated set

* link rubocop guideline to additional information

* fix typos and add trade-offs for using standard

---------

Co-authored-by: Neil Carvalho <me@neil.pro>

Author: vburzynski

.markdownlint-cli2.jsonc

@@ -149,7 +149,7 @@
 
     /* MD052 - Reference links and images should use a label that is defined */
     "reference-links-images": {
-      "shortcut_syntax": true
+      "shortcut_syntax": false
     },
 
     /* MD053 - Link and image reference definitions should be needed */

ruby/README.md

@@ -2,8 +2,7 @@
 
 [Sample 1](sample_1.rb) [Sample 2](sample_2.rb)
 
-- Use an opinionated set of rules for Rubocop. Prefer [standard] for new projects.
-  - Having an already decided configuration removes bikeshedding on what a Rubocop configuration should be.
+- [Use an opinionated set of rules for Rubocop](./Use an opinionated set of rules for Rubocop.md)
 - Avoid conditional modifiers (lines that end with conditionals). [36491dbb9]
 - Avoid multiple assignments per line (`one, two = 1, 2`). [#109]
 - Avoid organizational comments (`# Validations`). [#63]
@@ -42,7 +41,6 @@
 - Prefer `private` when indicating scope. Use `protected` only with comparison
   methods like `def ==(other)`, `def <(other)`, and `def >(other)`.
 
-[standard]: https://github.com/testdouble/standard
 [#63]: https://github.com/thoughtbot/guides/pull/63
 [#109]: https://github.com/thoughtbot/guides/pull/109
 [#122]: https://github.com/thoughtbot/guides/pull/122

ruby/Use an opinionated set of rules for Rubocop.md

@@ -0,0 +1,27 @@
+# Use an opinionated set of rules for Rubocop
+
+Ruby code can be written in many different styles and still be syntactically correct. The presence of divergent style and
+format can disrupt communication as well as complicate feature development. Code that exhibits a consistent style is
+easier to understand and maintain. The absence of consistent enforced style can result in unnecessary code churn.
+
+**Therefore:** Use an opinionated set of rules for Rubocop when coding in Ruby.
+
+- Prefer [standard] for new projects.
+- By employing an already decided configuration, you avoid bikeshedding on what the Rubocop configuration should be.
+- Code that is consistently formatted and styled will be easier to work with.
+
+There are, however, a few reasons one might choose not to introduce Standard in a project:
+
+- Change for the sake of change can be disruptive
+- An existing project may already employ it's own opinionated configuration of Rubocop and that set of rules is working.
+- A large project, which does not already use Standard, might require a costly amount of time to refactor and retrofit
+  existing code to conform to a new set of conventions.
+- There exists a need or desire to use Cops which are disabled by Standard
+- [standard] presents a lightweight but sensible set of style rules to focus on coding
+- [standard] prevents you from using cops that it disables
+
+Overall, the goal is to increase the quality and consistency of code while not getting distracted by disproportionally
+minor or trivial details. It's more important for an implementation team to agree to follow shared conventions than it
+is to enforce a specific configuration.
+
+[standard]: https://github.com/testdouble/standard