diff --git a/_data/docs.yml b/_data/docs.yml index fa1c057..7d6fd00 100644 --- a/_data/docs.yml +++ b/_data/docs.yml @@ -28,12 +28,15 @@ - tactic-ddd - application-and-process-layer - user-requirements + - stakeholders + - value-registers - imports - title: Analysis and Design Transformations docs: - rapid-ooad - story-splitting + - stakeholder-and-value-modelling-transformations - title: Architectural Refactorings (ARs) docs: @@ -50,6 +53,10 @@ - ar-change-shared-kernel-to-partnership - ar-change-partnership-to-shared-kernel +- title: Value-Driven Analysis and Design + docs: + - vdad-support + - title: Service Cutter docs: - service-cutter-context-map-suggestions diff --git a/_docs/generators/generic-freemarker-generator.md b/_docs/generators/generic-freemarker-generator.md index b16d88b..6750ba9 100644 --- a/_docs/generators/generic-freemarker-generator.md +++ b/_docs/generators/generic-freemarker-generator.md @@ -489,3 +489,4 @@ The project currently contains the following example templates: * Ubiquitous language glossary written in Markdown (currently a full report) * Currently a full report of the model. A future version of the template will generate a glossary only. * [JHipster Domain Language (JDL)](https://www.jhipster.tech/jdl/) template to [generate Microservices from CML models](/docs/jhipster-microservice-generation/) + * CSV files to export stakeholder and value register data (as part of the [VDAD support](/docs/vdad-support/)) diff --git a/_docs/generators/plant-uml.md b/_docs/generators/plant-uml.md index b8e50a4..d66f4db 100644 --- a/_docs/generators/plant-uml.md +++ b/_docs/generators/plant-uml.md @@ -26,10 +26,22 @@ Your CML models can define the lifecycle of Aggregates either in the [Aggregate ![PlantUML State Diagram](/img/QuoteRequestFlow_BC_InsuranceQuotes_QuoteRequestFlow_StateDiagram_with-end-States.png) ## UML Use Case Diagrams -CML also allows you to write Use Cases and User Stories. You can find the documentation about how to write such user requirements [here](/docs/user-requirements/). In case your CML model contains such user requirements, the PlantUML generator will also automatically generate a use case diagram for you. Here an example: +CML also allows you to write Use Cases and User Stories. You can find the documentation about how to write such user requirements [here](/docs/user-requirements/). In case your CML model contains such user requirements, the PlantUML generator will also automatically generate a use case diagram for you. Here is an example: ![PlantUML Use Case Diagram](/img/plantuml-generation-use-case-diagram-example.png) +## Stakeholder Maps +As documented [here](/docs/stakeholders/), CML allows you to model the stakeholders for a specific project, system or feature. In case your CML file contains such a `Stakeholders` section with stakeholders and stakeholder groups, the PlantUML generator will automatically generate a stakeholder map for you. An example: + +![PlantUML Stakeholder Map](/img/stakeholder-map-sdd-sample-simple.png) + +For more information about stakeholder maps and the idea behind them, we refer to the [Value-Driven Analysis and Design (VDAD)](https://ethical-se.github.io/value-driven-analysis-and-design) process. + +## Value Impact Maps +In case you modelled a value register in CML, which you can do as documented [here](/docs/value-registers/), the PlantUML generator will automatically create a so-called "Value Impact Map", a [Value-Driven Analysis and Design (VDAD)](https://ethical-se.github.io/value-driven-analysis-and-design) practice. An exemplary output is: + +![PlantUML Value Impact Map](/img/value-impact-map-sdd-sample.png) + ## Generating the PlantUML Diagrams The generators can be called from the context menus of the CML editors in VS Code or Eclipse. A documentation how to call the generators can also be found [here](/docs/generators/#using-the-generators). diff --git a/_docs/language-reference/stakeholders.md b/_docs/language-reference/stakeholders.md new file mode 100644 index 0000000..d5062e0 --- /dev/null +++ b/_docs/language-reference/stakeholders.md @@ -0,0 +1,113 @@ +--- +title: Stakeholders +permalink: /docs/stakeholders/ +--- + +The CML language supports the modelling of [stakeholders](https://en.wikipedia.org/wiki/Project_stakeholder) of (digital) solutions and/or projects. This feature has been introduced to support the [Value-Driven Analysis and Design (VDAD)](https://ethical-se.github.io/value-driven-analysis-and-design) process. One part of this process supporting ethical software engineering is the identification of all relevant stakeholders. For more information about the whole process we refer to the [VDAD page](https://ethical-se.github.io/value-driven-analysis-and-design). However, modelling stakeholders can support your requirements engineering process in different ways; no matter whether you apply VDAD practices or not. + +**Note**: With our [PlantUML generator](/docs/plant-uml/) you can automatically generate [Stakeholder Maps](https://ethical-se.github.io/value-driven-analysis-and-design/practices/stakeholder-mapping), once you modelled all your stakeholders and stakeholder groups. See example below. + +## Stakeholders Container +On the root level of a CML file, one first needs to create a `Stakeholders` container. This can be done as simply as follows: + +
Stakeholders {
+
+  // add stakeholders and stakeholder groups here
+
+}
+
+ +However, if you want to model the stakeholders for a specific [Bounded Context](/docs/bounded-context/), you can declare that as follows: + +
BoundedContext ExampleContext
+
+Stakeholders of ExampleContext {
+
+  // add stakeholders and stakeholder groups here
+
+}
+
+ +## Stakeholders +Inside a `Stakeholders` container, you can define your stakeholders. This can be done with the `Stakeholder` keyword an the name of the stakeholder: + +
BoundedContext ExampleContext
+
+Stakeholders of ExampleContext {
+
+  Stakeholder Shopper
+
+  Stakeholder Software_Engineer
+
+  Stakeholder Architect
+
+  // etc.
+
+}
+
+
+ +In addition, you can provide additional information for a stakeholder using the `description`, `influence` and `interest` keywords: + +
BoundedContext ExampleContext
+
+Stakeholders of ExampleContext {
+
+  Stakeholder Shopper {
+    description "Is using the shopping system to by everday goods."
+    
+    influence MEDIUM
+    interest HIGH
+  }
+
+}
+
+
+ +The `description` just describes why and/or how the stakeholder uses the system or is impacted by the system. As suggested by many stakeholder mapping tutorials (see [Miro](https://miro.com/blog/stakeholder-mapping/) or [Mural](https://www.mural.co/blog/stakeholder-mapping)), you can define what the `influence` of the stakeholders is and how much they are interested (`interest`) in the new system or feature. + +## Stakeholder Groups +Stakeholder maps often group stakeholders of similar roles or with similar interest together. This is also possible in CML with the `StakeholderGroup` keyword, which can again contain stakeholders with the `Stakeholder` keyword: + +
BoundedContext ExampleContext
+
+Stakeholders of ExampleContext {
+
+  StakeholderGroup Online_Shopping_Company {
+    Stakeholder Development_Team {
+      influence MEDIUM
+      interest HIGH
+    }
+    Stakeholder Product_Management {
+      influence HIGH
+      interest HIGH
+    }
+    Stakeholder Customer_Relationship_Manager {
+      influence HIGH
+      interest MEDIUM
+    }
+  }
+
+  Stakeholder Shopper {
+    description "Is using the shopping system to by everday goods."
+    
+    influence MEDIUM
+    interest HIGH
+  }
+
+}
+
+
+ +## Visualization: Stakeholder Map +Once your stakeholders are modelled in CML, you can generate a visual stakeholder map automatically. Here is an example: + +![Sample Stakeholder Map (for a new 'same day delivery' feature for an online shop)](./../../img/stakeholder-map-sdd-sample-simple.png) + +Check out our [PlantUML generator](/docs/plant-uml/) on how to generate such a diagram. + +## Stakeholders Export to CSV +In addition to the Stakeholder Map visualization, you can export your modelled stakeholder data as a CSV file. To do so, use the Freemarker temple [here](https://raw.githubusercontent.com/ContextMapper/context-mapper-dsl/master/org.contextmapper.dsl.ui/samples/freemarker/csv-files/stakeholders.csv.ftl) together with our [Generic Generator (Freemarker Templating)](/docs/generic-freemarker-generator/). + +## Transformations +Note that we offer several transformations that might help modelling stakeholders and their values according to [VDAD (Value-Driven Analysis and Design)](https://ethical-se.github.io/value-driven-analysis-and-design) more efficiently. The transformations are documented on the following page: [Stakeholder and Value Modelling Transformations](/docs/stakeholder-and-value-modelling-transformations/) diff --git a/_docs/language-reference/user-requirements.md b/_docs/language-reference/user-requirements.md index 14eb371..320a467 100644 --- a/_docs/language-reference/user-requirements.md +++ b/_docs/language-reference/user-requirements.md @@ -95,3 +95,16 @@ First and foremost, a user story is an invitation to communicate and collaborate *Note:* As you can see above, both variants allow users to specify multiple _interactions_ or _I want to_ parts in one use case or user story. You can see this as a way of expressing related features, for instance those originating from splitting a larger story - or the steps in a use case scenario. + +### Story Valuation +Since Context Mapper version 6.12.x, the user story syntax supports [story valuation](https://github.com/ethical-se/ese-practices/blob/main/practices/ESE-StoryValuation.md). A user story with the existing `As a`, `I want to` and `so that` parts can now be enhanced with promoted and harmed [ethical values](https://github.com/ethical-se/ese-practices/blob/v11/ESE-Glossary.md#ethical-value), as shown in the following example: + +
UserStory SampleStory {
+  As a "prospective customer of Lakeside Mutual" // a fictitious insurance company
+  I want to "manage" the "PersonalDataProfile" 
+  so that "I am offered a valid and fair insurance rate"
+  and that "data privacy" is promoted
+  accepting that "accountability and auditability" are harmed
+}
+
+
diff --git a/_docs/language-reference/values.md b/_docs/language-reference/values.md new file mode 100644 index 0000000..ea476c5 --- /dev/null +++ b/_docs/language-reference/values.md @@ -0,0 +1,285 @@ +--- +title: Value Registers +permalink: /docs/value-registers/ +--- + +The CML language supports the modelling of stakeholders and their values that might be strengthened or harmed by digital systems. This feature has been introduced to support the [Value-Driven Analysis and Design (VDAD)](https://ethical-se.github.io/value-driven-analysis-and-design) process. Context Mapper and the language concepts documented on this page therefore support the modelling of ethical concerns in software projects. For more information about the whole process we refer to the [VDAD page](https://ethical-se.github.io/value-driven-analysis-and-design). + +**Note**: Some of the terminology of the language, such as value register or value cluster, is based on the [IEEE Standard Model Process for Addressing Ethical Concerns during System Design (a.k.a. IEEE 7000 standard)](https://ieeexplore.ieee.org/document/9536679). Access to IEEE 7000 standard is free after registration for IEEE Xplore (click on "Access via Subscription"). However, you do not necessarily need to know that terminology; you can also simply model the values of your stakeholders within a `ValueRegister` block. + +## Value Register +If you are interested in reading more about the ideas of a _value register_, we refer to the [IEEE 7000 standard](https://ieeexplore.ieee.org/document/9536679) or the [ESE Glossary](https://github.com/ethical-se/ese-practices/blob/main/ESE-Glossary.md). However, if you just want to move on quickly and model the values of your stakeholders - just consider the value register a _container object_ that allows to model values for a specific Bounded Context: + +
BoundedContext Online_Shop_Same_Day_Delivery
+
+ValueRegister SDD_Stakeholder_Values for Online_Shop_Same_Day_Delivery {
+  // model values inside value register
+}
+
+
+ +If you just want to start to model some values without separating by Bounded Contexts, you can create a `ValueRegister` without that reference: + +
ValueRegister SDD_Stakeholder_Values {
+  // model values inside value register
+}
+
+
+ +## Values + +Inside a value register you can define the values important to your project, software and/or feature: + +
ValueRegister SDD_Stakeholder_Values {
+  
+  Value Privacy
+  Value Respect
+  Value Integrity
+  Value Love
+  // etc.
+
+}
+
+
+ +The following attributes that can be added, namely whether a value is a _core value_, _value demonstrators_, _related values_ and _opposing values_, follow the terminology of the [IEEE 7000 standard](https://ieeexplore.ieee.org/document/9536679). We refer to the standard for a more detailed introduction into these terms; in CML the attributes are however not mandatory. + +
ValueRegister SDD_Stakeholder_Values {
+  
+  Value Privacy {
+    isCore
+
+    demonstrator = "right to be left alone"
+    demonstrator = "the right to refuse sharing private data"
+    relatedValue = "Intimacy"
+    opposingValue = "Transparency"
+    opposingValue = "Inclusiveness"
+  }
+
+}
+
+
+ +As always in CML, the 'equal' (=) sign is optional: + +
ValueRegister SDD_Stakeholder_Values {
+  
+  Value Privacy {
+    isCore
+
+    demonstrator "right to be left alone"
+    demonstrator "the right to refuse sharing private data"
+    relatedValue "Intimacy"
+    opposingValue "Transparency"
+    opposingValue "Inclusiveness"
+  }
+
+}
+
+
+ +
+Note: Just modelling values, as seen here, does not allow you to generate any visualization yet (at least for now). Continue with the section Stakeholder Priorisation, Impact & Consequences, to define how important these values are to individual stakeholders and how these stakeholders are affected. After that, you can generate a [Value Impact Map](https://ethical-se.github.io/value-driven-analysis-and-design/practices/value-impact-mapping) with the PlantUML generator. +
+ +## Value Clusters + +If one applies or follows the [IEEE 7000 standard](https://ieeexplore.ieee.org/document/9536679), values are clustered around core values. For example, the value _confidentiality_ (a demonstrator could be: _right to be left alone_), is an enabler for the core value of _privacy_. Therefore the value _confidentiality_ would be added to the value cluster with the core value _privacy_. This can be modelled in CML as follows: + +
ValueRegister SDD_Stakeholder_Values {
+  
+  ValueCluster Privacy {
+    core PRIVACY
+
+    Value Confidentiality {
+      demonstrator = "right to be left alone"  
+    }
+  }
+
+}
+
+
+ +The _core value_ can be modelled as shown above, by using the enumeration CML provides. That enumeration contains all _core values_ according to the [IEEE 7000 standard](https://ieeexplore.ieee.org/document/9536679): `AUTONOMY`, `CARE`, `CONTROL`, `FAIRNESS`, `INCLUSIVENESS`, `INNOVATION`, `PERFECTION`, `PRIVACY`, `RESPECT`, `SUSTAINABILITY`, `TRANSPARENCY`, `TRUST`. + +Alteratively, you can define the core value by a custom string: + +
ValueRegister SDD_Stakeholder_Values {
+  
+  ValueCluster MyCluster {
+    core "Respect"
+  }
+
+}
+
+
+ +Further note that the attributes `demonstrator`, `relatedValue` and `opposingValue`, as documented for the `Value` object already, can also be applied to value clusters: + +
ValueRegister SDD_Stakeholder_Values {
+  
+  ValueCluster Privacy {
+    core PRIVACY
+
+    demonstrator = "right to be left alone"
+    demonstrator = "the right to refuse sharing private data"
+    relatedValue = "Intimacy"
+    opposingValue = "Transparency"
+    opposingValue = "Inclusiveness"
+  }
+
+}
+
+
+ +Generally, you can cluster values in CML but you do not necessarily have to. + +
+Note: Just modelling values and value clusters as seen here does not yet allow you to generate any visualization (at least for now). Continue with the section Stakeholder Priorisation, Impact & Consequences, to define how important these values are to the individual stakeholders and how they are affected. After that step, you can generate a Value Impact Map with the PlantUML generator. +
+ +## Stakeholder Prioritization, Impact & Consequences + +Note that the following model snippets require stakeholder modelling as precondition; please check the page [Stakeholders](/docs/stakeholders/) for the corresponding CML syntax. + +The following example illustrates how you can assign the values ​​to the stakeholders who care about them. For each stakeholder you can define the `PRIORITY` this value has for the stakeholder, as well as the `IMPACT`. The `consequences` section allows you to model `good`, `bad`, and `neutral` consequences your system or feature has to the given value - from the perspective of the specific stakeholder: + +
BoundedContext SameDayDelivery
+
+Stakeholders of SameDayDelivery {
+  StakeholderGroup Customers_and_Shoppers
+  StakeholderGroup Delivery_Staff_of_Suppliers
+}
+
+ValueRegister SD_Values for SameDayDelivery {  
+  Value Freedom {
+      Stakeholder Customers_and_Shoppers {
+        priority HIGH
+        impact MEDIUM
+        consequences
+          good "increased freedom"
+      }
+      Stakeholder Delivery_Staff_of_Suppliers {
+        priority HIGH
+        impact HIGH
+        consequences
+          bad "work-life-balance"
+      }
+    }
+}
+
+
+ +This is again possible on the level of a `Value`, but as well on a `ValueCluster`: + +
BoundedContext SameDayDelivery
+
+Stakeholders of SameDayDelivery {
+  StakeholderGroup Customers_and_Shoppers
+  StakeholderGroup Delivery_Staff_of_Suppliers
+}
+
+ValueRegister SD_Values for SameDayDelivery {  
+  ValueCluster Freedom {
+      core AUTONOMY
+      Stakeholder Customers_and_Shoppers {
+        priority HIGH
+        impact MEDIUM
+        consequences
+          good "increased freedom"
+      }
+      Stakeholder Delivery_Staff_of_Suppliers {
+        priority HIGH
+        impact HIGH
+        consequences
+          bad "work-life-balance"
+      }
+    }
+}
+
+
+ +## Mitigation Actions + +In case your system has negative impact on values, you might want to model the mitigation actions you consider to implement to reduce harm. The following example shows how to model such mitigation actions in CML: + +
BoundedContext SameDayDelivery
+
+Stakeholders of SameDayDelivery {
+  StakeholderGroup Drivers
+}
+
+ValueRegister SD_Values for SameDayDelivery {  
+  Value WorkLifeBalance {
+    demonstrator "Drivers value a healthy work-life-balance"
+    Stakeholder Drivers {
+      priority HIGH
+      impact HIGH
+      consequences
+        bad "SDD will harm work-life-balance of drivers"
+          action "hire more drivers" ACT
+    }
+  }
+}
+
+
+ +The action types can be `ACT` (actively do something to reduce harm to values), `MONITOR` (just monitor the issue; maybe to gather more information), or a custom string. + +## Example +For a complete example, we refer to the [example repository](https://github.com/ContextMapper/context-mapper-examples). You can find a complete CML model for the "Same Day Delivery" example there. + +Once you have modelled your values and stakeholder priorities and impact, you can generate a [Value Impact Map (VDAD practice)](https://ethical-se.github.io/value-driven-analysis-and-design/practices/value-impact-mapping). The diagram is part of the [PlantUML generator](/docs/plant-uml/). + +![Exemplary Value Impact Map - Generated out of a CML model with the PlantUML generator](./../../img/value-impact-map-sdd-sample.png) + +## Stakeholders Export to CSV +In addition to the Value Impact Map visualization, you can export your modelled value register data as a CSV file. To do so, use the Freemarker temple [here](https://raw.githubusercontent.com/ContextMapper/context-mapper-dsl/master/org.contextmapper.dsl.ui/samples/freemarker/csv-files/value-registers.csv.ftl) together with our [Generic Generator (Freemarker Templating)](/docs/generic-freemarker-generator/). + +## Additional ESE Formats + +The following additional (experimental) CML features allow users to apply [Story Valuation](https://github.com/ethical-se/ese-practices/blob/main/practices/ESE-StoryValuation.md) as proposed in the Ethical Software Engineering (ESE) practice repository. Three ESE notations are supported: _Value Epic_, _Value Weighting_ and _Value Narrative_. + +
+Note: These language features are experimental and currently not used by any generator. The modelled information can therefore not be visualized, except you use the Generic Generator (Templating with Freemarker) and process the data on your own. +
+ +
Stakeholders {
+  Stakeholder Conference_Participant
+}
+
+ValueRegister Conference_Management_Sample {  
+  ValueEpic Data_Privacy {
+    As a Conference_Participant
+    I value "data privacy"
+    as demonstrated in 
+      realization of "confidentiality of sensitive personal information such as my passport number" 
+      reduction of "efficiency of operations for conference mansagement staff"
+  }
+
+  ValueWeigthing Data_Privacy {
+    In the context of the SOI,
+    stakeholder Conference_Participant values "data privacy" more than "efficiency from a registration management staff point of view"
+    expecting benefits such as "confidentiality of sensitive personal information"
+    running the risk of harms such as "higher conference fees and a slower registration process."
+  }
+}
+
+ValueRegister Same_Day_Delivery_Sample {
+  ValueNarrative Sample_Narrative {
+    When the SOI executes "the same say delivery epic (incl. split user stories that meet the INVEST criteria)",
+    stakeholders expect it to promote, protect or create "freedom and quality of life",
+    possibly degrading or prohibiting "work-life balance of suppliers and shopper privacy"
+    with the following externally observable and/or internally auditable behavior:
+
+    "Given: Shop is operational and suited suppliers and logistics firms are available. 
+    When: Same day delivery is promised during order acceptance and confirmation. 
+    Then: Order arrives at shipment address until 11:59pm on the same say."
+  }
+}
+
+
+ +## Transformations +Note that we offer several transformations that might help modelling stakeholders and their values according to [VDAD (Value-Driven Analysis and Design)](https://ethical-se.github.io/value-driven-analysis-and-design) more efficiently. The transformations are documented on the following page: [Stakeholder and Value Modelling Transformations](/docs/stakeholder-and-value-modelling-transformations/). + diff --git a/_docs/modeling-tools/stakeholder-and-value-modelling.md b/_docs/modeling-tools/stakeholder-and-value-modelling.md new file mode 100644 index 0000000..cd32c64 --- /dev/null +++ b/_docs/modeling-tools/stakeholder-and-value-modelling.md @@ -0,0 +1,78 @@ +--- +title: Stakeholder and Value Modelling Transformations +permalink: /docs/stakeholder-and-value-modelling-transformations/ +image: /img/cm-og-image.png +--- + +The following transformations aim at making modelling [stakeholders](/docs/stakeholders/) and [value registers](/docs/value-registers/) more efficient. These language features and transformations shall provide tool-support for applying the [Value-Driven Analysis and Design (VDAD) process](https://ethical-se.github.io/value-driven-analysis-and-design). + +## Add Ethical Value Assessment to User Story +As documented under [User Requirements](/docs/user-requirements/) CML provides language features to write user stories and in addition, [Story Valuation according to ESE](https://github.com/ethical-se/ese-practices/blob/main/practices/ESE-StoryValuation.md). + +If you have an existing user story in CML that has not been valuated yet, a transformation allows you to generate the additional part: + +![Add Ethical Value Assessment - Example (1)](/img/add-ethical-value-assessment-sample-1.png) + +This will add the additional part for the story valuation: + +![Add Ethical Value Assessment - Example (2)](/img/add-ethical-value-assessment-sample-2.png) + +You can then adjust the story with the actual values that are promoted and/or harmed. For example: + +![Add Ethical Value Assessment - Example (3)](/img/add-ethical-value-assessment-sample-3.png) + +## Create Stakeholder for User Story Role +When applying [Value-Driven Analysis and Design (VDAD)](https://ethical-se.github.io/value-driven-analysis-and-design) or similar approaches, one typically starts with modelling requirements (use cases, user stories, etc.) and then continues with a stakeholder analysis and, later on, elicits ethical values. This transformation allows you to create stakeholders directly from roles inside user stories. + +The following example shows such a user story and the transformation you can trigger: + +![Create Stakeholder for User Story Role - Example (1)](/img/create-stakeholder-for-story-role-sample-1.png) + +The transformation will create a `Stakeholders` block with the corresponding stakeholder for your user story role: + +![Create Stakeholder for User Story Role - Example (2)](/img/create-stakeholder-for-story-role-sample-2.png) + +Note that the values for `influence`, `interest` and `description` are just generated default values that you have to adjust manually. + + +## Create Value for Stakeholder +Once you modelled a stakeholder, you may want to elicit the values that are important for this stakeholder(s). This transformation allows you to automatically generate a CML `Value` construct for a given stakeholder. + +The following example shows the transformation offered on stakeholders: + +![Create Value for Stakeholder - Example (1)](/img/create-value-for-stakeholder-sample-1.png) + +The transformation will create a value register containing a value and the reference to the stakeholder: + +![Create Value for Stakeholder - Example (2)](/img/create-value-for-stakeholder-sample-2.png) + +**Note** that this transformation generates lots of default values, such as register name, value name, etc., that you have to manually change/define after applying the transformation. + +## Create Value Register for Bounded Context +If you already created a domain model and defined a Bounded Context in CML, you might want to generate a [Value Register](/docs/value-registers/) for the specific Bounded Context. This transformation allows you to quickly add a register with the reference to your context. + +The following example illustrates the transformation offered on Bounded Contexts: + +![Create Value Register for Bounded Context - Example (1)](/img/create-value-register-for-bounded-context-sample-1.png) + +The transformation creates an empty value register for the context, which can then be filled with the values important to the stakeholders: + +![Create Value Register for Bounded Context - Example (2)](/img/create-value-register-for-bounded-context-sample-2.png) + +## Wrap Value in Cluster +If you have modelled a value inside a value register and now want to use value clusters according to the [IEEE 7000 standard](https://ieeexplore.ieee.org/document/9536679), this transformations allows you to wrap an existing value inside a value cluster. + +The following example shows the offered transformation on a value: + +![Wrap Value in Cluster - Example (1)](/img/wrap-value-in-cluster-sample-1.png) + +The transformation wraps the value accordingly: + +![Wrap Value in Cluster - Example (2)](/img/wrap-value-in-cluster-sample-2.png) + +Note that you have to adjust the name of the cluster manually after applying the transformation. + +**Note:** This transformation ("Wrap Value in Cluster") has some known technical limitations in Visual Studio Code. We are sorry for that. For the time being, use the Eclipse Plugin if you want to test this transformation. + +## Feedback +Please feel free to provide feedback which other transformations would be useful for you. [Get in touch with us](/getting-involved/). diff --git a/_docs/value-driven-analysis-and-design/vdad-support.md b/_docs/value-driven-analysis-and-design/vdad-support.md new file mode 100644 index 0000000..fb324a9 --- /dev/null +++ b/_docs/value-driven-analysis-and-design/vdad-support.md @@ -0,0 +1,36 @@ +--- +title: "Value-Driven Analysis and Design (VDAD) Support" +permalink: /docs/vdad-support/ +--- + +Context Mapper offers tool support for multiple steps of the [Value-Driven Analysis and Design](https://ethical-se.github.io/value-driven-analysis-and-design) process (such as [Stakeholder Mapping](https://ethical-se.github.io/value-driven-analysis-and-design/practices/stakeholder-mapping) and [Value Impact Mapping](https://ethical-se.github.io/value-driven-analysis-and-design/practices/value-impact-mapping)) as well as [Story Valuation](https://github.com/ethical-se/ese-practices/blob/main/practices/ESE-StoryValuation.md) by [Ethical Software Engineering (ESE)](https://github.com/ethical-se/ese-practices). + +## Language Features + +The following pages document the CML features that support modelling stakeholders of a project or system and the ethical values important to them: + + * [Stakeholder](/docs/stakeholders/) + * [Value Registers](/docs/value-registers/) + * [User Requirements (see "Story Valuation")](/docs/user-requirements/#story-valuation) + +## Transformations + +Context Mapper provides several transformations that ease the modelling of stakeholders and their values. These transformations are documented [here](/docs/stakeholder-and-value-modelling-transformations/). + +## Generators + +By using the language features mentioned above, you can automatically generate: + + * [Stakeholder Maps](https://ethical-se.github.io/value-driven-analysis-and-design/practices/stakeholder-mapping) with our [PlantUML generator](/docs/plant-uml/) + * [Value Impact Maps](https://ethical-se.github.io/value-driven-analysis-and-design/practices/value-impact-mapping) with our [PlantUML generator](/docs/plant-uml/) + * CSV files with the stakeholder data by using our [Generic Generator (Freemarker Templating)](/docs/generic-freemarker-generator/) + * CSV files with the value register data by using our [Generic Generator (Freemarker Templating)](/docs/generic-freemarker-generator/) + +**Note**: The freemarker templates can be found [here](https://github.com/ContextMapper/context-mapper-dsl/tree/master/org.contextmapper.dsl.ui/samples/freemarker/csv-files). + +## Background and Further Information + +For more information about the project and our initiatives towards ethical- and value-driven (software) engineering we refer to our project repositories: + + * [Value-Driven Analysis and Design (VDAD)](https://github.com/ethical-se/value-driven-analysis-and-design) + * [Ethical Software Engineering (ESE)](https://github.com/ethical-se/ese-practices) diff --git a/_news/2024-08-26-v6.12.0-released.md b/_news/2024-08-26-v6.12.0-released.md new file mode 100644 index 0000000..8a820b9 --- /dev/null +++ b/_news/2024-08-26-v6.12.0-released.md @@ -0,0 +1,118 @@ +--- +layout: news +title: "v6.12.0 - Stakeholder and Value Modelling Support" +author: Stefan Kapferer +image: /img/cm-og-image.png +--- + +We are happy to announce a new Context Mapper release (v6.12.0 released today), which supports new modelling features towards ethical- and value-driven (software) engineering! Concretely, we support [Value-Driven Analysis and Design (VDAD)](https://ethical-se.github.io/value-driven-analysis-and-design) practices as well as [ESE (Ethical Software Engineering)](https://github.com/ethical-se/ese-practices). + +In summary, the release offers the following new features: + + * Modelling [Stakeholders](/docs/stakeholders/) that are relevant to and/or concerned about your project, system, feature, product, etc. + * Modelling ethical [Values ("Value Registers")](/docs/value-registers/) that are important to your stakeholders and are impacted by the system or feature you are aiming to build. + * Extension of the [User Story syntax](/docs/user-requirements/#story-valuation) according to the [Story Valuation](https://github.com/ethical-se/ese-practices/blob/main/practices/ESE-StoryValuation.md) practice in ESE. + * Generation of [Stakeholder Maps](https://ethical-se.github.io/value-driven-analysis-and-design/practices/stakeholder-mapping) with our [PlantUML generator](/docs/plant-uml/). + * Generation of [Value Impact Maps](https://ethical-se.github.io/value-driven-analysis-and-design/practices/value-impact-mapping) with our [PlantUML generator](/docs/plant-uml/). + * Generation of CSV files with the modelled stakeholder and value data using our [Generic Generator (Freemarker Templating)](/docs/generic-freemarker-generator/). + * New Freemarker templates are available [here](https://github.com/ContextMapper/context-mapper-dsl/tree/master/org.contextmapper.dsl.ui/samples/freemarker/csv-files). + * [Transformations](/docs/stakeholder-and-value-modelling-transformations/) that support the modelling of stakeholders and values in CML. + * Adjustment of the [Use Case diagram generation with PlantUML](/docs/plant-uml/): all features (`I want to`-parts of user stories) are now added to the diagram. + +The page [Value-Driven Analysis and Design (VDAD) Support](/docs/vdad-support/) summarizes the new features supporting [VDAD](https://ethical-se.github.io/value-driven-analysis-and-design) and [ESE](https://github.com/ethical-se/ese-practices) as well. + +## Stakeholder Modelling +The CML language offers to features that allow you to model your stakeholders and stakeholder groups. More details can be found on the corresponding [documentation page](/docs/stakeholders/); the following example gives a first impression: + +
BoundedContext ExampleContext
+
+Stakeholders of ExampleContext {
+
+  StakeholderGroup Online_Shopping_Company {
+    Stakeholder Development_Team {
+      influence MEDIUM
+      interest HIGH
+    }
+    Stakeholder Product_Management {
+      influence HIGH
+      interest HIGH
+    }
+    Stakeholder Customer_Relationship_Manager {
+      influence HIGH
+      interest MEDIUM
+    }
+  }
+
+  Stakeholder Shopper {
+    description "Is using the shopping system to by everday goods."
+    
+    influence MEDIUM
+    interest HIGH
+  }
+
+}
+
+
+ +## Value Register Modelling +In addition to stakeholders and stakeholder groups, one can now model the values important to these human beings in CML. An example: + +
BoundedContext SameDayDelivery
+
+Stakeholders of SameDayDelivery {
+  StakeholderGroup Customers_and_Shoppers
+  StakeholderGroup Delivery_Staff_of_Suppliers
+}
+
+ValueRegister SD_Values for SameDayDelivery {  
+  ValueCluster Freedom {
+      core AUTONOMY
+      Stakeholder Customers_and_Shoppers {
+        priority HIGH
+        impact MEDIUM
+        consequences
+          good "increased freedom"
+      }
+      Stakeholder Delivery_Staff_of_Suppliers {
+        priority HIGH
+        impact HIGH
+        consequences
+          bad "work-life-balance"
+      }
+    }
+}
+
+
+ +More details about the language features are documented [here](/docs/value-registers/). Note that the term "value register" comes from the [IEEE Standard Model Process for Addressing Ethical Concerns during System Design (a.k.a. IEEE 7000 standard)](https://ieeexplore.ieee.org/document/9536679) (note: access to IEEE 7000 is free after registration for IEEE Xplore (click on "Access via Subscription").). The CML features support that terminology, but you can model values without knowledge about the standard; just checkout the [documentation page](/docs/value-registers/). The [ESE glossary](https://github.com/ethical-se/ese-practices/blob/main/ESE-Glossary.md) might be interesting for you, in case you still want to have some brief summaries of the most important terms of the IEEE 7000 standard. + +## Stakeholder Map Generation +Once one has modelled the stakeholders of the project, system or feature, the [PlantUML generator](/docs/plant-uml/) now generates a [Stakeholder Map](https://ethical-se.github.io/value-driven-analysis-and-design/practices/stakeholder-mapping) automatically. The following example gives as a first impression: + +![Stakeholder Map Example](/img/stakeholder-map-sdd-sample-simple.png) + +## Value Impact Map Generation +The [PlantUML generator](/docs/plant-uml/) further supports the visualization of the modelled values and their impact on your stakeholders - it automatically generates a [Value Impact Map](https://ethical-se.github.io/value-driven-analysis-and-design/practices/value-impact-mapping). An example: + +![Value Impact Map Example](/img/value-impact-map-sdd-sample.png) + +## CSV File Generation +If you want to export all stakeholder and/or value data that you have modelled in CML (for example, for further processing with other tools), we provide a CSV export. Exporting the data to CSV can be done with our [Generic Generator (Freemarker Templating)](/docs/generic-freemarker-generator/). You can find the Freemarker templates [here](https://github.com/ContextMapper/context-mapper-dsl/tree/master/org.contextmapper.dsl.ui/samples/freemarker/csv-files). + +Please note that the CSV file generation currently cannot handle (replace) commas that you add to Strings of your CML model. In case you want to use CSV export, please avoid commas in your CML model string values. + +## New Transformations +Several new transformations support you when modelling stakeholders and value registers. Check out the corresponding [documentation page](/docs/stakeholder-and-value-modelling-transformations/). + +## Use Case Diagram Adjustment +**Note**: This change is not related to the [VDAD support](/docs/vdad-support/). + +We adjusted the Use Case diagram generated by the [PlantUML generator](/docs/plant-uml/) in order to let the `I want to` parts of user stories or `interactions` of use cases also make it into the generated diagrams. For example, the `I want to`-parts of the following user stories did not appear in the generated diagram so far: + +![Multiple 'I want to'-parts within User Story - An example](/img/use-case-adjustment-feature-notes-1.png) + +With this release, we now generator all features into the notes of the Use Case diagram: + +![Use Case diagram with all features in Note - An example](/img/use-case-adjustment-feature-notes-2.png) + +As always, if you have any issues or other feedback, please [let us know](/getting-involved/). diff --git a/img/add-ethical-value-assessment-sample-1.png b/img/add-ethical-value-assessment-sample-1.png new file mode 100644 index 0000000..814aa67 Binary files /dev/null and b/img/add-ethical-value-assessment-sample-1.png differ diff --git a/img/add-ethical-value-assessment-sample-2.png b/img/add-ethical-value-assessment-sample-2.png new file mode 100644 index 0000000..b165b0a Binary files /dev/null and b/img/add-ethical-value-assessment-sample-2.png differ diff --git a/img/add-ethical-value-assessment-sample-3.png b/img/add-ethical-value-assessment-sample-3.png new file mode 100644 index 0000000..79847a6 Binary files /dev/null and b/img/add-ethical-value-assessment-sample-3.png differ diff --git a/img/create-stakeholder-for-story-role-sample-1.png b/img/create-stakeholder-for-story-role-sample-1.png new file mode 100644 index 0000000..3b92318 Binary files /dev/null and b/img/create-stakeholder-for-story-role-sample-1.png differ diff --git a/img/create-stakeholder-for-story-role-sample-2.png b/img/create-stakeholder-for-story-role-sample-2.png new file mode 100644 index 0000000..f77a182 Binary files /dev/null and b/img/create-stakeholder-for-story-role-sample-2.png differ diff --git a/img/create-value-for-stakeholder-sample-1.png b/img/create-value-for-stakeholder-sample-1.png new file mode 100644 index 0000000..e3646b4 Binary files /dev/null and b/img/create-value-for-stakeholder-sample-1.png differ diff --git a/img/create-value-for-stakeholder-sample-2.png b/img/create-value-for-stakeholder-sample-2.png new file mode 100644 index 0000000..6b796e6 Binary files /dev/null and b/img/create-value-for-stakeholder-sample-2.png differ diff --git a/img/create-value-register-for-bounded-context-sample-1.png b/img/create-value-register-for-bounded-context-sample-1.png new file mode 100644 index 0000000..d2689aa Binary files /dev/null and b/img/create-value-register-for-bounded-context-sample-1.png differ diff --git a/img/create-value-register-for-bounded-context-sample-2.png b/img/create-value-register-for-bounded-context-sample-2.png new file mode 100644 index 0000000..5c7ebd3 Binary files /dev/null and b/img/create-value-register-for-bounded-context-sample-2.png differ diff --git a/img/stakeholder-map-sdd-sample-simple.png b/img/stakeholder-map-sdd-sample-simple.png new file mode 100644 index 0000000..e425e2f Binary files /dev/null and b/img/stakeholder-map-sdd-sample-simple.png differ diff --git a/img/use-case-adjustment-feature-notes-1.png b/img/use-case-adjustment-feature-notes-1.png new file mode 100644 index 0000000..da14dee Binary files /dev/null and b/img/use-case-adjustment-feature-notes-1.png differ diff --git a/img/use-case-adjustment-feature-notes-2.png b/img/use-case-adjustment-feature-notes-2.png new file mode 100644 index 0000000..9ca7b6d Binary files /dev/null and b/img/use-case-adjustment-feature-notes-2.png differ diff --git a/img/value-impact-map-sdd-sample.png b/img/value-impact-map-sdd-sample.png new file mode 100644 index 0000000..bfecc1a Binary files /dev/null and b/img/value-impact-map-sdd-sample.png differ diff --git a/img/wrap-value-in-cluster-sample-1.png b/img/wrap-value-in-cluster-sample-1.png new file mode 100644 index 0000000..37157a1 Binary files /dev/null and b/img/wrap-value-in-cluster-sample-1.png differ diff --git a/img/wrap-value-in-cluster-sample-2.png b/img/wrap-value-in-cluster-sample-2.png new file mode 100644 index 0000000..886a9e3 Binary files /dev/null and b/img/wrap-value-in-cluster-sample-2.png differ