More examples and explanations added and linked, template tweaks

Author: socadk

docs/decisions/0018-use-confirmation-as-heading.md

@@ -31,6 +31,6 @@ We wanted to enable also less formal checks.
 
 ### Confirmation
 
-* Before next release, check that there is at least one more example.
-* Before each release, check that templates are still consistent with this decision (or update AD).
-* Monitor [GitHub issues](https://github.com/adr/madr/issues) for feedback on examples and template/tool change requests periodically.
+* Before next release; check that there is at least one example that has a "Confirmation" section.
+* Before each release: check that templates and examples are still consistent with this decision (or update AD).
+* Continuously: Monitor [GitHub issues](https://github.com/adr/madr/issues) for feedback on examples and template/tool change requests periodically.

docs/examples.md

@@ -5,6 +5,7 @@ nav_order: 2
 
 MADR is a template allowing to craft short, medium-sized, and large decision records.
 There is no formal definition of short, medium-sized, and large decision records.
+
 The following sections present an example in the context of assertion frameworks for Java.
 We start with presenting a very short and dense version:
 It "just" lists the context and problem statement, the available options, and the outcome.
@@ -68,9 +69,9 @@ Chosen option: "Plain JUnit5", because comes out best (see "Pros and Cons of the
 
 ### Confirmation
 
-* Check project dependencies, JUnit5 should appear (and be the only test assertion library)
-* Collect experience with JUnit5 in sprint reviews and retrospectives: does experience match the pros and cons evaluation below?
-* Decide whether and when to review the decision (the 'R' in the [ecADR definition of done](https://medium.com/olzzio/a-definition-of-done-for-architectural-decisions-426cf5a952b9) for ADs) 
+* Check project dependencies, JUnit5 should appear (and be the only test assertion library).
+* Collect experience with JUnit5 in sprint reviews and retrospectives: does the gained experience match the pros and cons evaluation below?
+* Decide whether and when to review the decision (this is the 'R' in the [ecADR definition of done](https://medium.com/olzzio/a-definition-of-done-for-architectural-decisions-426cf5a952b9) for ADs).
 
 ## Pros and Cons of the Options
 
@@ -129,3 +130,9 @@ assertThat(markdownFormatter.format(source))
 
 German comparison between Hamcrest and AssertJ: <https://www.sigs-datacom.de/uploads/tx_dmjournals/philipp_JS_06_15_gRfN.pdf>.
 ````
+
+## More Examples
+
+["https://medium.com/olzzio/the-markdown-adr-madr-template-explained-and-distilled-b67603ec95bb"](https://medium.com/olzzio/the-markdown-adr-madr-template-explained-and-distilled-b67603ec95bb) provides another example (under "Example of Filled Out Template").
+
+And the [decisions folder](/docs/decisions/) in this repository provides examples as well.

template/0000-use-markdown-architectural-decision-records.md

@@ -19,7 +19,7 @@ Chosen option: "MADR 4.0.0", because
 
 * Implicit assumptions should be made explicit.
   Design documentation is important to enable people understanding the decisions later on.
-  See also [A rational design process: How and why to fake it](https://doi.org/10.1109/TSE.1986.6312940).
+  See also ["A rational design process: How and why to fake it"](https://doi.org/10.1109/TSE.1986.6312940).
 * MADR allows for structured capturing of any decision.
 * The MADR format is lean and fits our development style.
 * The MADR structure is comprehensible and facilitates usage & maintenance.

template/adr-template-bare-minimal.md

@@ -1,5 +1,5 @@
 
-# {short title of solved problem and solution}
+# {short title, representative of solved problem and found solution}
 
 ## Context and Problem Statement
 

template/adr-template-bare.md

@@ -6,7 +6,7 @@ consulted:
 informed: 
 ---
 
-# {short title of solved problem and solution}
+# {short title, representative of solved problem and found solution}
 
 ## Context and Problem Statement
 
@@ -41,6 +41,6 @@ informed:
 * <!-- * Neutral, because -->
 * <!-- * Bad, because -->
 
-   
 ## More Information
 
+

template/adr-template-minimal.md

@@ -1,4 +1,4 @@
-# {short title of solved problem and solution}
+# {short title, representative of solved problem and found solution}
 
 ## Context and Problem Statement
 

template/adr-template.md

@@ -1,12 +1,13 @@
 ---
-# These are optional elements. Feel free to remove any of them.
+# These are optional metadata elements. Feel free to remove any of them.
 status: "{proposed | rejected | accepted | deprecated | … | superseded by [ADR-0005](0005-example.md)}"
 date: {YYYY-MM-DD when the decision was last updated}
 decision-makers: {list everyone involved in the decision}
 consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
 informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}
 ---
-# {short title of solved problem and solution}
+
+# {short title, representative of solved problem and found solution}
 
 ## Context and Problem Statement