Bug fixes and consistency edits in README and examples

Author: socadk

README.md

@@ -8,7 +8,7 @@ This repository provides YAML ADR templates and examples.
 
 * [YAML port of the Markdown Architectural Decisions (MADR) template](templates/yadr-template-full.yaml), as well as a [usage example](examples/yadr-template-full-example.yaml) for it.
   * [Bare version of the YADR template](templates/yadr-template-bare.yaml) and shortened [usage example](examples/yadr-template-bare-example.yaml).
-  * [JSON conversions](examples-validation) of the YADR usage examples validate against the [JSON schema](schemas/yadr-schema.json) for the template. Note that the schema contains a placeholder ?`id-of-option-1` for the option name in its `pros-and-cons-of-the-options` object; this placeholder has to bne replaced by an existing option name if the validation is supposed to check this part. <!-- Note that this schema has been designed to validate all array elements, which requires the type definitions of the array elements to be scalar; see answer 1 to the question ["How do I make a jsonschema so that it validates all objects in array?"](https://stackoverflow.com/questions/49319692/how-do-i-make-a-jsonschema-so-that-it-validates-all-objects-in-array) on Stack Overflow for rationale -->
+  * [JSON conversions](examples-validation) of the YADR usage examples validate against the [JSON schema](schemas/yadr-schema.json) for the template. Note that the schema contains a placeholder `id-of-option-1` for the option name in its `pros-and-cons-of-the-options` object; this placeholder has to bne replaced by an existing option name if the validation is supposed to check this part (in the examples, the option names are `yaml`, `madr` and `json)`. <!-- Note that this schema has been designed to validate all array elements, which requires the type definitions of the array elements to be scalar; see answer 1 to the question ["How do I make a jsonschema so that it validates all objects in array?"](https://stackoverflow.com/questions/49319692/how-do-i-make-a-jsonschema-so-that-it-validates-all-objects-in-array) on Stack Overflow for rationale -->
 * The folder [other YAML templates](templates/other-yaml-templates/) contains YAML ports of templates not originating from the MADR project, for instance, the [Y-Statement](https://medium.com/olzzio/y-statements-10eb07b5a177) template.
   * An [example](examples/other-yaml-templates/yaml-as-additional-y-statement-syntax.yaml) and two corresponding [JSON conversions](examples-validation/other-yaml-templates/) are available as well.
 

examples-validation/use-yaml-as-adr-syntax.json

@@ -14,12 +14,12 @@
     "Ability to write rich text with item lists, **bold** and *italic* settings, tables, hyperlinks"
   ],
   "considered-options": [
-    "Markdown with additional semantic anchors",
+    "Markdown ADRs with additional semantic anchors",
     "JSON and JSON Schema",
     "[YAML](https://yaml.org/) with JSON Schema validation"
   ],
   "pros-and-cons-of-the-options": {
-    "madr": {
+    "Markdown": {
       "pros": [
         "good for humans"
       ],
@@ -31,15 +31,15 @@
         "open source tooling project stalled"
       ]
     },
-    "json": {
+    "JSON": {
       "pros": [
         "good for machines"
       ],
       "cons": [
         "readability for humans debatable"
       ]
     },
-    "yaml": {
+    "YAML": {
       "pros": [
         "best of both worlds, many tools"
       ],