Merge sections "Positive Consequences" and "Negative Consequences" (#81)

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 ### Changed
 
 - Moved section "Validation" directly after "Decision Outcome"
+- Merged sections "Positive Consequences" and "Negative Consequences" into "Consequences" to enable similar grammar as in "Pros and Cons of the Options". [#75](https://github.com/adr/madr/issues/75)
 
 ### Removed
 

docs/decisions/0004-write-own-toc-tool.md

@@ -10,7 +10,7 @@ ADRs have to be indexed somehow. E.g., for offering a website showing all ADRs.
 
 ## Considered Options
 
-* Write the own tool `adr-log`
+* Write own tool `adr-log`
 * Use `adr-tools`' TOC functionality
 
 ## Decision Outcome
@@ -23,10 +23,7 @@ Chosen option: "Write own tool `adr-log`", because
 We accept that changing `adr-tools` would also be possible.
 It is prepared to included header and footer: <https://github.com/npryce/adr-tools/blob/master/tests/generate-contents-with-header-and-footer.sh>.
 
-### Positive Consequences
+### Consequences
 
-* `adr-log` is installable using `npm install -g adr-log`, which is easier than installing `adr-tools`.
-
-### Negative consequences
-
-* Another tool has to be maintained
+* Good, because `adr-log` is installable using `npm install -g adr-log`, which is easier than installing `adr-tools`.
+* Bad, because another tool has to be maintained

docs/decisions/0017-use-same-format-for-outcomes-and-options.md

@@ -0,0 +1,26 @@
+---
+parent: Decisions
+nav_order: 17
+---
+# Use Same Format for Outcomes and Options
+
+## Context and Problem Statement
+
+"Outcome" has "Positive Consequences" and "Negative Consequences" sections. "Options" just have a single list with "Good" and "Bad" prefixes.
+
+Ticket: [issue#75](https://github.com/adr/madr/issues/75)
+
+## Decision Drivers
+
+* Consistent design of MADR
+* Allow easy copy and paste
+
+## Considered Options
+
+* Section "Consequences" listing positive and negative consequences as "Good, because" and "Bad, because"
+* Section "Consequences" listing positive and negative consequences as "Positive, because" and "Negative, because"
+* No sections "Consequences", "Positive Consequences", and "Negative Consequences"
+
+## Decision Outcome
+
+Chosen option: 'Section "Consequences" listing positive and negative consequences as "Good, because" and "Bad, because"', because resolves all forces.

docs/decisions/adr-template.md

@@ -40,16 +40,11 @@ Chosen option: "{title of option 1}", because
 {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
 
 <!-- This is an optional element. Feel free to remove. -->
-### Positive Consequences
+### Consequences
 
-* {e.g., improvement of one or more desired qualities, …}
-* …
-
-<!-- This is an optional element. Feel free to remove. -->
-### Negative Consequences
-
-* {e.g., compromising one or more desired qualities, …}
-* …
+* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
+* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
+* … <!-- numbers of consequences can vary -->
 
 <!-- This is an optional element. Feel free to remove. -->
 ## Validation

docs/examples.md

@@ -59,15 +59,12 @@ How to write readable test assertions for advanced tests?
 
 Chosen option: "Plain JUnit5", because comes out best (see below).
 
-### Positive Consequences
+### Consequences
 
-* Tests are more readable
-* More easy to write tests
-* More readable assertions
-
-### Negative Consequences
-
-* More complicated testing leads to more complicated assertions
+* Good, because tests are more readable
+* Goop, because more easy to write tests
+* Good, because more readable assertions
+* Bad, because more complicated testing leads to more complicated assertions
 
 ## Pros and Cons of the Options
 
@@ -78,12 +75,14 @@ JabRef testing guidelines: <https://devdocs.jabref.org/getting-into-the-code/cod
 
 Example:
 
-    String actual = markdownFormatter.format(source);
-    assertTrue(actual.contains("Markup<br />"));
-    assertTrue(actual.contains("<li>list item one</li>"));
-    assertTrue(actual.contains("<li>list item 2</li>"));
-    assertTrue(actual.contains("> rest"));
-    assertFalse(actual.contains("\n"));
+```java
+String actual = markdownFormatter.format(source);
+assertTrue(actual.contains("Markup<br />"));
+assertTrue(actual.contains("<li>list item one</li>"));
+assertTrue(actual.contains("<li>list item 2</li>"));
+assertTrue(actual.contains("> rest"));
+assertFalse(actual.contains("\n"));
+```
 
 * Good, because Junit5 is "common Java knowledge"
 * Bad, because complex assertions tend to get hard to read
@@ -103,12 +102,14 @@ Homepage: <https://joel-costigliola.github.io/assertj/>
 
 Example:
 
-    assertThat(markdownFormatter.format(source))
-            .contains("Markup<br />")
-            .contains("<li>list item one</li>")
-            .contains("<li>list item 2</li>")
-            .contains("> rest")
-            .doesNotContain("\n");
+```java
+assertThat(markdownFormatter.format(source))
+        .contains("Markup<br />")
+        .contains("<li>list item one</li>")
+        .contains("<li>list item 2</li>")
+        .contains("> rest")
+        .doesNotContain("\n");
+```
 
 * Good, because offers fluent assertions
 * Good, because allows partial string testing to focus on important parts
@@ -121,4 +122,3 @@ Example:
 ## More Information
 
 German comparison between Hamcrest and AssertJ: <https://www.sigs-datacom.de/uploads/tx_dmjournals/philipp_JS_06_15_gRfN.pdf>.
-```

template/adr-template.md

@@ -33,16 +33,11 @@ Chosen option: "{title of option 1}", because
 {justification. e.g., only option, which meets k.o. criterion decision driver | which resolves force {force} | … | comes out best (see below)}.
 
 <!-- This is an optional element. Feel free to remove. -->
-### Positive Consequences
+### Consequences
 
-* {e.g., improvement of one or more desired qualities, …}
-* …
-
-<!-- This is an optional element. Feel free to remove. -->
-### Negative Consequences
-
-* {e.g., compromising one or more desired qualities, …}
-* …
+* Good, because {positive consequence, e.g., improvement of one or more desired qualities, …}
+* Bad, because {negative consequence, e.g., compromising one or more desired qualities, …}
+* … <!-- numbers of consequences can vary -->
 
 <!-- This is an optional element. Feel free to remove. -->
 ## Validation