From df1542bdbd574f79370779f2966a244088d9d72d Mon Sep 17 00:00:00 2001
From: "Allen D. Householder" <ahouseholder@users.noreply.github.com>
Date: Fri, 17 Nov 2023 11:15:57 -0500
Subject: [PATCH] add ADR about excluding examples from object descriptions
 (#391)

---
 .../adr/0007-descriptions-exclude-examples.md | 75 +++++++++++++++++++
 docs/adr/index.md                             | 27 ++++---
 2 files changed, 91 insertions(+), 11 deletions(-)
 create mode 100644 docs/adr/0007-descriptions-exclude-examples.md

diff --git a/docs/adr/0007-descriptions-exclude-examples.md b/docs/adr/0007-descriptions-exclude-examples.md
new file mode 100644
index 00000000..36699d94
--- /dev/null
+++ b/docs/adr/0007-descriptions-exclude-examples.md
@@ -0,0 +1,75 @@
+---
+status: "accepted"
+date: 2023-11-17
+deciders: adh, jspring
+---
+# Object Descriptions Exclude Examples
+
+## Context and Problem Statement
+
+In written definitions of a Decision Point, Decision Point 
+Value, Outcome Group, Outcome Value, or other elements, it is common to 
+include examples in the text. In terms of documentation, this is a worthy 
+practice to promote understanding.
+
+Examples are sometimes timely and need to be updated even though the
+underlying concept has not changed. This can lead to unnecessary
+versioning of objects.
+
+## Decision Drivers
+
+- In the course of modeling CVSS vectors across versions as SSVC decision 
+  points, we have found that concepts change less often than examples.
+- Our preference is to minimize version changes to objects unless the 
+  underlying concept has changed.
+
+## Considered Options
+
+- Include examples in descriptions of objects.
+- Exclude examples from descriptions of objects.
+
+## Decision Outcome
+
+Chosen option: "Exclude examples from descriptions of objects", because this 
+helps to minimize version changes to objects unless the underlying concept
+has changed.
+
+Examples may be included in the documentation text surrounding the object 
+definition, but not in the object definition itself.
+
+### Consequences
+
+- Good, because it reduces the likelihood and frequency of version changes to 
+  objects.
+- Good, because it promotes the use of examples in documentation text.
+- Bad, because it may make it more difficult to understand the object 
+  definition solely from the object definition itself.
+
+### Confirmation
+
+The implementation of this decision is confirmed by the absence of examples
+in the object definitions.
+
+When generating an object definition from a text description, object 
+creators should look out for phrases like "for example" and "an example of 
+this is" and exclude the example from the object definition.
+
+## Pros and Cons of the Options
+
+### Option 1: Include examples in descriptions of objects
+
+- Good, because it makes the object definition easier to understand as a standalone
+  element.
+- Bad, because it lengthens the object definition.
+- Bad, because it may lead to unnecessary versioning of objects.
+
+### Option 2: Exclude examples from descriptions of objects
+
+See [Decision Outcome](#decision-outcome).
+
+## More Information
+
+- [ADR-0006](0006-ssvc-decision-point-versioning-rules.md) - SSVC Decision 
+  Point Versioning Rules
+- [ADR-0005](0005-ssvc-decision-point-group-versioning.md) - SSVC Decision 
+  Point Group Versioning Rules
diff --git a/docs/adr/index.md b/docs/adr/index.md
index 4ba7fdab..f2812c84 100644
--- a/docs/adr/index.md
+++ b/docs/adr/index.md
@@ -1,27 +1,32 @@
-<!-- This file has been generated by `pyadr`. Manual changes will be erased at next generation. -->
 # Architecture Decision Records
 
 ## Accepted Records
 
-* [0000 - Record architecture decisions](0000-record-architecture-decisions.md)
-* [0001 - Use Markdown Architectural Decision Records](0001-use-markdown-architectural-decision-records.md)
-* [0002 - SSVC Decision Points are versioned using Semantic Versioning](0002-ssvc-decision-points-are-versioned.md)
-* [0003 - SSVC Decision Points Versioning Rules](0003-ssvc-decision-point-versioning-rules.md)
-* [0004 - SSVC Decision Point Groups are Versioned using SemVer](0004-ssvc-decision-point-groups-are-versioned.md)
-* [0005 - SSVC Decision Point Group Versioning Rules](0005-ssvc-decision-point-group-versioning.md)
+- [0000 - Record architecture decisions](0000-record-architecture-decisions.md)
+- [0001 - Use Markdown Architectural Decision Records]
+  (0001-use-markdown-architectural-decision-records.md)
+- [0002 - SSVC Decision Points are versioned using Semantic Versioning]
+  (0002-ssvc-decision-points-are-versioned.md)
+- [0004 - SSVC Decision Point Groups are Versioned using SemVer]
+  (0004-ssvc-decision-point-groups-are-versioned.md)
+- [0005 - SSVC Decision Point Group Versioning Rules]
+  (0005-ssvc-decision-point-group-versioning.md)
+- [0006 - SSVC Decision Points Versioning Rules]
+  (0006-ssvc-decision-point-versioning-rules.md)
 
 ## Rejected Records
 
-* None
+- None
 
 ## Superseded Records
 
-* None
+- [0003 - SSVC Decision Points Versioning Rules]
+(0003-ssvc-decision-point-versioning-rules.md)
 
 ## Deprecated Records
 
-* None
+- None
 
 ## Records with non-standard statuses
 
-* None
+- None