Bug fixes and small edits

ESE-BackgroundInformation.md

@@ -5,6 +5,7 @@
 ## Method (Processes, Concepts) Overview
 
 IEEE Std. 7000 advises how to go from context to value to requirements to design:
+<!-- TODO (v2): could call out Clauses in standard that introduce the concepts (processes that produce the artifacts) -->
 
 ![From Value to Requirements to Design](/images/ESE-ConceptsAndTraceRelations.png)
 
@@ -35,7 +36,7 @@ The Scrum concept of [Product Vision](https://www.scrum.org/resources/what-produ
 | Clause 7: Concept of Operations (ConOps)[^1] and Context Exploration Process [^2] | no direct pendant; epics as input | Concepts in HCI/UX community such as personas, Context Diagram in DPR |
 | Clause 8: Ethical Values Elicitation and Prioritization Process | User Stories and related practices (e.g., [backlog refinement/grooming](https://www.agilealliance.org/glossary/backlog-refinement/)) | Novel practice in ESE: [Story Valuation](./practices/ESE-StoryValuation.md) |
 | Clause 9: Ethical Requirements Definition Process | User Stories and related practices | Mapping, splitting; estimation/planning games such as [planning poker]() |
-| Clause 10: Ethical Risk-Based Design Process | n/a (implicit, evolutionary/emerging) | Domain-Driven Design, "Just Enoughhttps://www.agilealliance.org/glossary/planning-poker/ Architecture" (related [patterns](https://socadk.github.io/patterns/reading-lists/agile-architecture.html)) |
+| Clause 10: Ethical Risk-Based Design Process | n/a (implicit, evolutionary/emerging) | Related books: "Domain-Driven Design" (E. Evans), "Just Enough Architecture" (G. Fairbanks), also see related [patterns](https://socadk.github.io/patterns/reading-lists/agile-architecture.html) |
 | Clause 11: Transparency Management Process | no direct mapping | [Ethical Review Meeting/Report](./practices/ESE-EthicalReview.md), in ESE design decision logs from DPR |
 
 [^1]: Note that the term "operations" in ConOps refers to the functioning of an application or system here; it is not to be confused with the Ops in DevOps and systems/service management (superset relation). IEEE Std. 7000 defines ConOps as "verbal and/or graphic statement, in broad outline, of an organization’s assumptions or intent in regard to an operation or series of operations" and then "The concept is designed to give an overall picture of the organization operations". ConOps has its roots in ISO/IEC/IEEE15288:2015.

ESE-Glossary.md

@@ -50,7 +50,7 @@ IEEE Std. 7000: "ethical value: Value in the context of human culture that suppo
 
 ### EVR 
 
-EVR stands for ethical value requirement (EVR). An EVR is an "organizational or technical requirement catering to values that stakeholders and conceptual value analysis identified as relevant for the SOI."
+EVR stands for Ethical Value Requirement (EVR). An EVR is an "organizational or technical requirement catering to values that stakeholders and conceptual value analysis identified as relevant for the SOI."
 
 ### Harm
 
@@ -70,6 +70,7 @@ IEEE Std. 7000 defines: "Group containing one core value and several values inst
 
 In ESE, value clusters can be documented in several ways, for instance as part of Value Trees (see example in Story Valuation). ESE also provides Markdown templates for them.
 
+
 ### Value Register
 
 IEEE Std. 7000 defines: "An information store created for transparency and traceability reasons, which contains data and decisions gained in ethical values elicitation and prioritization and traceability into ethical value requirements." 

practices/ESE-StoryValuation.md

@@ -9,6 +9,7 @@ Output: New or updated Value Register, EVRs, (optional) VBSRs
 Activity: *Story Valuation*
 ---------------------------
 also known as Value-Enhanced User Story Elicitation, People-Society-Planet INVESTing 
+<!-- 4852 words on Oct 25, 2023 -->
 
 *Quick links:* (1) [Goal and Purpose](#goal-and-purpose) (2) [Notations](#notations) (3) [Techniques](#valuation-techniques) (4) [Usage](#usage) (5) [Application Hints](#hints-and-pitfalls-to-avoid) (6) [Other Practices](/practices/) (7) [ESE Home](/README.md)
 
@@ -57,6 +58,8 @@ The following UML object instance diagram (aka Value Tree) illustrates the relat
 
 ![ESE/IEEE 7000 Value Tree](/images/ESE-ValueObjectTree.png)
 
+<!-- TODO (H) comment on L1 value vs. Value Demonstator (see ISD paper notes) -->
+
 Note that the words [benefits](/ESE-Glossary.md#benefit) and [harms](/ESE-Glossary.md#harm) in the figure do not imply the usage, or sole usage, of any particular ethical theory.  
 
 ### Notation(s)
@@ -79,7 +82,7 @@ This value cluster has [H, M, L] priority for me.
 
 Values can be positive or negative in a given context; IEEE Std. 7000 explains that in Annex "B.3 Value axioms" (so absence of certain values, the negative ones, is good!). The wording in the template is inspired by the definition of terms in the standard. <!-- also used: "creation" and "prohibition" -->
 
-b) Complementarily and/or alternatively, a relative *Value Weighting* makes a consideration/assessment explicit. It may look like this:
+b) Complementary and/or alternatively, a relative *Value Weighting* makes a consideration/assessment explicit. It may look like this:
 
 ~~~
 In the context of SOI [Name],
@@ -121,11 +124,11 @@ In ESE, EVRs may take the standard story form, slightly extended with a brief et
 As a [role]
 I want to [action/feature]
 so that [benefit] is achieved 
-  and that [Values a, b, c] are promoted,
-  accepting that [Values x, y, z] are reduced.
+  and that [values a, b, c] are promoted,
+  accepting that [values x, y, z] are reduced.
 ~~~
 
-Alternatively, the value-enhanced user story may also refer to Value Register entries, possibly expressed as Value Epics, Value Weightings and/or Value Narratives (as introduced previously). Note that risk treatment options and value demonstrator information is not made explicit in this template; such information can be added in free form.
+Alternatively, the value-enhanced user story may also refer to Value Register entries, possibly expressed as Value Epics, Value Weightings and/or Value Narratives (as introduced previously). Note that risk treatment options and value demonstrators are not made explicit in this template; such information can be added in free form.
 
 #### Value-Based System Requirement (VBSRs)
 
@@ -251,7 +254,7 @@ NOTE: Opposing values can be positive or negative."
 The following steps can be followed when applying the technique: 
 
 1. *Pick 2-3 core values from the table.* Use the information in the columns "Related value" and "Opposing value" columns in Table G.1 to make them more complete, concrete, and tangible.
-2. *Explain the relevance of each core value in the given project/product context by way of example and/or refinement.* You might want to tell a story and/or point out the positive and negative consequences of this value in the form of a narrative or demonstrator (see column in table above). This information may come from the Value Register of the project/product development effort when IEEE Std. 7000 is followed (if no Value Register exists yet, it is a good time to create one now).  
+2. *Explain the relevance of each core value in the given project/product context by way of example and/or refinement.* You might want to tell a story and/or point out the positive and negative consequences of this value in the form of a narrative (see column in table above). This information may come from the Value Register of the project/product development effort when IEEE Std. 7000 is followed (if no Value Register exists yet, it is a good time to create one now).  
 3. *Prioritize the value(s), either absolutely or relatively.* For instance, you may want to use a writing style similar to that in the Agile Manifesto ("We value mm over nn").
 
 Repeat these steps for each stakeholder group. Keep an eye on effort, focus on and begin with high-priority, high-impact values. 
@@ -438,8 +441,8 @@ ESE does not contain any design practices at present; the [Design Practice Repos
 Ethical values and ways to handle them are explained here: 
 
 * The article ["Human Values as the Basis for Sustainable Information System Design"](https://research.wu.ac.at/ws/portalfiles/portal/19837176/Human+Values+as+the+Basis+for+Stustainable+Information+Systems+Design+%28Pre-print%29.pdf) has many more examples of values.
-* Literature on Material Value Ethics may help with prioritization: 
-  * For instance, Table B.1 in Annex B of IEEE Std. 7000 summarizes five principles for value ranking and provides examples. And Table D.1 in Annex D lists legal, societal, and environmental feasibility study guidelines (pages 62 to 64). 
+* IEEE Std. 7000 and literature on "Material Value Ethics" may help with prioritization: 
+  * For instance, advice is given on in Clause 8.3, Step d) on page 41; seven types of ethical considerations and three external sources are listed. Table B.1 in Annex B of IEEE Std. 7000 summarizes five principles for value ranking and provides examples; Table D.1 in Annex D lists legal, societal, and environmental feasibility study guidelines (pages 62 to 64). 
   * And ["Value-Sensitive Design"](https://mitpress.mit.edu/9780262039536/value-sensitive-design/) compiles 13 human values in Table 2.1 on page 28; Table 3.1 on pages 61 to 64 summarizes 17 value-sensitive design methods.
 * A 2019 conference presentation by Jennifer Riggins called ["How (and Why) to Factor Tech Ethics into Your Sprint"](https://www.infoq.com/presentations/tech-ethics-sprint/) and her article ["Tech Ethics New Year’s Resolution: Don’t Build Software You Will Regret"](https://thenewstack.io/tech-ethics-new-years-resolution-dont-build-software-you-will-regret/) ask valuation questions, effectively forestalling/antedating our three valuation techniques, for instance "What is the worst possible use case for this code?" Other questions concern connectivity and data transfer as well as data storage and lifetime.
 * Annex B of IEEE Std. 7000 covers value concepts, starting from philosophical foundations in B1; B2 presents an example and B.4 covers value ranking. Annex C is about ethical theories applied to ethical value elicitation, for instance, utilitarian ethics, virtue ethics, and duty ethics.
@@ -465,7 +468,7 @@ The [Agile Glossary](https://www.agilealliance.org/agile101/agile-glossary/) is
 ```yaml
 title: "ESE activity: Story Valuation"
 author: Olaf Zimmermann (ZIO)
-date: "11, 13, 2023 (Source: Project ESE)"
+date: "11, 20, 2023 (Source: Project ESE)"
 copyright: The author, 2023 (unless noted otherwise). All rights reserved.
 license: Creative Commons Attribution 4.0 International License
 ```

practices/README.md

@@ -1,21 +1,25 @@
 # Activities and artifacts in Ethical Software Engineering (ESE)
+<!-- 273 words on Oct 25, 2023 -->
 
 ESE extends three existing practices (activities, artifacts) and proposes two new ones. It also uses three existing ones (unchanged). 
 
 
 ## Practice (Activity/Artifact) Index 
 
-ESE includes a total of eight agile activities and artifacts, listed in alphabetical order here (which differs from usage flow):
+ESE includes a total of nine agile activities and artifacts, listed in alphabetical order here (which differs from usage flow):
 
+* (new) [Story Valuation](ESE-StoryValuation.md) activity, ***the entry point for ESE usage***
 * (unchanged) Acceptance Testing, see entry in [Agile Alliance Glossary](https://www.agilealliance.org/glossary/acceptance)
 * (extended artifact) [Definition of Done](ESE-DefinitionOfDone.md) 
 * (extended artifact) [Definition of Ready](ESE-DefinitionOfReady.md) 
 * (new) [Ethical Review](ESE-EthicalReview.md)
 * (unchanged) Product Backlog, see entry in [Agile Alliance Glossary](https://www.agilealliance.org/glossary/backlog/) 
 * (unchanged) Sprint Planning, see entry in [Agile Alliance Glossary](https://www.agilealliance.org/glossary/sprint-planning/)
-* (new) [Story Valuation](ESE-StoryValuation.md) activity, ***the entry point for ESE usage***
+* (unchanged) User Story, see entry in [Agile Alliance Glossary](https://www.agilealliance.org/glossary/user-stories/)
 * (extended activity) [Value Retrospective](ESE-ValueRetrospective.md) 
 
+<!-- TODO (H) v2: arrow between product backlog and unchanged ap missing (Jan 24) -->
+
 The following UML class diagram shows how these method elements relate to each other: 
 
 ![ESE Practices and Their Relations](/images/ESE-Practices.png)
@@ -31,6 +35,7 @@ The following figure shows how the IEEE Std. 7000 concepts are logically connect
 ![From Value to Requirements to Design](/images/ESE-ConceptsAndTraceRelations.png) 
 <!-- note: figure also used in ESE-BackgroundInformation.md -->
 
+EVR stands for [Ethical Value Requirement](/ESE-Glossary.md#evr), VBSR for [Value-Based System Requirement](/ESE-Glossary.md#vbsr).
 
 ## Other Repository Pages