diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..8a45331 --- /dev/null +++ b/.gitignore @@ -0,0 +1,20 @@ +# Github page +_site +.sass-cache +.jekyll-metadata +*.gem +.bundle +vendor/bundle + +Gemfile.lock + +# IDEs +.idea/ +**/*.iml + +# Output dirs +**/out +**/bin +**/target +**/src-gen + diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..95abffc --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,20 @@ +# Contributing to VDAD + +Contribution is always welcome! Here are some ways how you can contribute: + + * Did you find a typo or smaller errors? Just create Pull Request (PR) in [this repository](https://github.com/ethical-se/value-driven-analysis-and-design). + * You want to suggest improvements or have ideas how to enhance to project? Feel free to [create a GitHub issue](https://github.com/ethical-se/value-driven-analysis-and-design/issues)! + +## Getting in Touch + +For anything else, such as discussing collaboration opportunities, [please contact us](https://www.ost.ch/de/person/stefan-kapferer-2046). + +## License +This work is licensed under a +[Creative Commons Attribution 4.0 International License][cc-by]. + +[![CC BY 4.0][cc-by-image]][cc-by] + +[cc-by]: http://creativecommons.org/licenses/by/4.0/ +[cc-by-image]: https://i.creativecommons.org/l/by/4.0/88x31.png +[cc-by-shield]: https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..ee1be0d --- /dev/null +++ b/Gemfile @@ -0,0 +1,2 @@ +gem "github-pages", group: :jekyll_plugins +gem "webrick" diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..56902ed --- /dev/null +++ b/LICENSE @@ -0,0 +1,396 @@ +Attribution 4.0 International + +======================================================================= + +Creative Commons Corporation ("Creative Commons") is not a law firm and +does not provide legal services or legal advice. Distribution of +Creative Commons public licenses does not create a lawyer-client or +other relationship. Creative Commons makes its licenses and related +information available on an "as-is" basis. Creative Commons gives no +warranties regarding its licenses, any material licensed under their +terms and conditions, or any related information. Creative Commons +disclaims all liability for damages resulting from their use to the +fullest extent possible. + +Using Creative Commons Public Licenses + +Creative Commons public licenses provide a standard set of terms and +conditions that creators and other rights holders may use to share +original works of authorship and other material subject to copyright +and certain other rights specified in the public license below. The +following considerations are for informational purposes only, are not +exhaustive, and do not form part of our licenses. + + Considerations for licensors: Our public licenses are + intended for use by those authorized to give the public + permission to use material in ways otherwise restricted by + copyright and certain other rights. Our licenses are + irrevocable. Licensors should read and understand the terms + and conditions of the license they choose before applying it. + Licensors should also secure all rights necessary before + applying our licenses so that the public can reuse the + material as expected. Licensors should clearly mark any + material not subject to the license. This includes other CC- + licensed material, or material used under an exception or + limitation to copyright. More considerations for licensors: + wiki.creativecommons.org/Considerations_for_licensors + + Considerations for the public: By using one of our public + licenses, a licensor grants the public permission to use the + licensed material under specified terms and conditions. If + the licensor's permission is not necessary for any reason--for + example, because of any applicable exception or limitation to + copyright--then that use is not regulated by the license. Our + licenses grant only permissions under copyright and certain + other rights that a licensor has authority to grant. Use of + the licensed material may still be restricted for other + reasons, including because others have copyright or other + rights in the material. A licensor may make special requests, + such as asking that all changes be marked or described. + Although not required by our licenses, you are encouraged to + respect those requests where reasonable. More_considerations + for the public: + wiki.creativecommons.org/Considerations_for_licensees + +======================================================================= + +Creative Commons Attribution 4.0 International Public License + +By exercising the Licensed Rights (defined below), You accept and agree +to be bound by the terms and conditions of this Creative Commons +Attribution 4.0 International Public License ("Public License"). To the +extent this Public License may be interpreted as a contract, You are +granted the Licensed Rights in consideration of Your acceptance of +these terms and conditions, and the Licensor grants You such rights in +consideration of benefits the Licensor receives from making the +Licensed Material available under these terms and conditions. + + +Section 1 -- Definitions. + + a. Adapted Material means material subject to Copyright and Similar + Rights that is derived from or based upon the Licensed Material + and in which the Licensed Material is translated, altered, + arranged, transformed, or otherwise modified in a manner requiring + permission under the Copyright and Similar Rights held by the + Licensor. For purposes of this Public License, where the Licensed + Material is a musical work, performance, or sound recording, + Adapted Material is always produced where the Licensed Material is + synched in timed relation with a moving image. + + b. Adapter's License means the license You apply to Your Copyright + and Similar Rights in Your contributions to Adapted Material in + accordance with the terms and conditions of this Public License. + + c. Copyright and Similar Rights means copyright and/or similar rights + closely related to copyright including, without limitation, + performance, broadcast, sound recording, and Sui Generis Database + Rights, without regard to how the rights are labeled or + categorized. For purposes of this Public License, the rights + specified in Section 2(b)(1)-(2) are not Copyright and Similar + Rights. + + d. Effective Technological Measures means those measures that, in the + absence of proper authority, may not be circumvented under laws + fulfilling obligations under Article 11 of the WIPO Copyright + Treaty adopted on December 20, 1996, and/or similar international + agreements. + + e. Exceptions and Limitations means fair use, fair dealing, and/or + any other exception or limitation to Copyright and Similar Rights + that applies to Your use of the Licensed Material. + + f. Licensed Material means the artistic or literary work, database, + or other material to which the Licensor applied this Public + License. + + g. Licensed Rights means the rights granted to You subject to the + terms and conditions of this Public License, which are limited to + all Copyright and Similar Rights that apply to Your use of the + Licensed Material and that the Licensor has authority to license. + + h. Licensor means the individual(s) or entity(ies) granting rights + under this Public License. + + i. Share means to provide material to the public by any means or + process that requires permission under the Licensed Rights, such + as reproduction, public display, public performance, distribution, + dissemination, communication, or importation, and to make material + available to the public including in ways that members of the + public may access the material from a place and at a time + individually chosen by them. + + j. Sui Generis Database Rights means rights other than copyright + resulting from Directive 96/9/EC of the European Parliament and of + the Council of 11 March 1996 on the legal protection of databases, + as amended and/or succeeded, as well as other essentially + equivalent rights anywhere in the world. + + k. You means the individual or entity exercising the Licensed Rights + under this Public License. Your has a corresponding meaning. + + +Section 2 -- Scope. + + a. License grant. + + 1. Subject to the terms and conditions of this Public License, + the Licensor hereby grants You a worldwide, royalty-free, + non-sublicensable, non-exclusive, irrevocable license to + exercise the Licensed Rights in the Licensed Material to: + + a. reproduce and Share the Licensed Material, in whole or + in part; and + + b. produce, reproduce, and Share Adapted Material. + + 2. Exceptions and Limitations. For the avoidance of doubt, where + Exceptions and Limitations apply to Your use, this Public + License does not apply, and You do not need to comply with + its terms and conditions. + + 3. Term. The term of this Public License is specified in Section + 6(a). + + 4. Media and formats; technical modifications allowed. The + Licensor authorizes You to exercise the Licensed Rights in + all media and formats whether now known or hereafter created, + and to make technical modifications necessary to do so. The + Licensor waives and/or agrees not to assert any right or + authority to forbid You from making technical modifications + necessary to exercise the Licensed Rights, including + technical modifications necessary to circumvent Effective + Technological Measures. For purposes of this Public License, + simply making modifications authorized by this Section 2(a) + (4) never produces Adapted Material. + + 5. Downstream recipients. + + a. Offer from the Licensor -- Licensed Material. Every + recipient of the Licensed Material automatically + receives an offer from the Licensor to exercise the + Licensed Rights under the terms and conditions of this + Public License. + + b. No downstream restrictions. You may not offer or impose + any additional or different terms or conditions on, or + apply any Effective Technological Measures to, the + Licensed Material if doing so restricts exercise of the + Licensed Rights by any recipient of the Licensed + Material. + + 6. No endorsement. Nothing in this Public License constitutes or + may be construed as permission to assert or imply that You + are, or that Your use of the Licensed Material is, connected + with, or sponsored, endorsed, or granted official status by, + the Licensor or others designated to receive attribution as + provided in Section 3(a)(1)(A)(i). + + b. Other rights. + + 1. Moral rights, such as the right of integrity, are not + licensed under this Public License, nor are publicity, + privacy, and/or other similar personality rights; however, to + the extent possible, the Licensor waives and/or agrees not to + assert any such rights held by the Licensor to the limited + extent necessary to allow You to exercise the Licensed + Rights, but not otherwise. + + 2. Patent and trademark rights are not licensed under this + Public License. + + 3. To the extent possible, the Licensor waives any right to + collect royalties from You for the exercise of the Licensed + Rights, whether directly or through a collecting society + under any voluntary or waivable statutory or compulsory + licensing scheme. In all other cases the Licensor expressly + reserves any right to collect such royalties. + + +Section 3 -- License Conditions. + +Your exercise of the Licensed Rights is expressly made subject to the +following conditions. + + a. Attribution. + + 1. If You Share the Licensed Material (including in modified + form), You must: + + a. retain the following if it is supplied by the Licensor + with the Licensed Material: + + i. identification of the creator(s) of the Licensed + Material and any others designated to receive + attribution, in any reasonable manner requested by + the Licensor (including by pseudonym if + designated); + + ii. a copyright notice; + + iii. a notice that refers to this Public License; + + iv. a notice that refers to the disclaimer of + warranties; + + v. a URI or hyperlink to the Licensed Material to the + extent reasonably practicable; + + b. indicate if You modified the Licensed Material and + retain an indication of any previous modifications; and + + c. indicate the Licensed Material is licensed under this + Public License, and include the text of, or the URI or + hyperlink to, this Public License. + + 2. You may satisfy the conditions in Section 3(a)(1) in any + reasonable manner based on the medium, means, and context in + which You Share the Licensed Material. For example, it may be + reasonable to satisfy the conditions by providing a URI or + hyperlink to a resource that includes the required + information. + + 3. If requested by the Licensor, You must remove any of the + information required by Section 3(a)(1)(A) to the extent + reasonably practicable. + + 4. If You Share Adapted Material You produce, the Adapter's + License You apply must not prevent recipients of the Adapted + Material from complying with this Public License. + + +Section 4 -- Sui Generis Database Rights. + +Where the Licensed Rights include Sui Generis Database Rights that +apply to Your use of the Licensed Material: + + a. for the avoidance of doubt, Section 2(a)(1) grants You the right + to extract, reuse, reproduce, and Share all or a substantial + portion of the contents of the database; + + b. if You include all or a substantial portion of the database + contents in a database in which You have Sui Generis Database + Rights, then the database in which You have Sui Generis Database + Rights (but not its individual contents) is Adapted Material; and + + c. You must comply with the conditions in Section 3(a) if You Share + all or a substantial portion of the contents of the database. + +For the avoidance of doubt, this Section 4 supplements and does not +replace Your obligations under this Public License where the Licensed +Rights include other Copyright and Similar Rights. + + +Section 5 -- Disclaimer of Warranties and Limitation of Liability. + + a. UNLESS OTHERWISE SEPARATELY UNDERTAKEN BY THE LICENSOR, TO THE + EXTENT POSSIBLE, THE LICENSOR OFFERS THE LICENSED MATERIAL AS-IS + AND AS-AVAILABLE, AND MAKES NO REPRESENTATIONS OR WARRANTIES OF + ANY KIND CONCERNING THE LICENSED MATERIAL, WHETHER EXPRESS, + IMPLIED, STATUTORY, OR OTHER. THIS INCLUDES, WITHOUT LIMITATION, + WARRANTIES OF TITLE, MERCHANTABILITY, FITNESS FOR A PARTICULAR + PURPOSE, NON-INFRINGEMENT, ABSENCE OF LATENT OR OTHER DEFECTS, + ACCURACY, OR THE PRESENCE OR ABSENCE OF ERRORS, WHETHER OR NOT + KNOWN OR DISCOVERABLE. WHERE DISCLAIMERS OF WARRANTIES ARE NOT + ALLOWED IN FULL OR IN PART, THIS DISCLAIMER MAY NOT APPLY TO YOU. + + b. TO THE EXTENT POSSIBLE, IN NO EVENT WILL THE LICENSOR BE LIABLE + TO YOU ON ANY LEGAL THEORY (INCLUDING, WITHOUT LIMITATION, + NEGLIGENCE) OR OTHERWISE FOR ANY DIRECT, SPECIAL, INDIRECT, + INCIDENTAL, CONSEQUENTIAL, PUNITIVE, EXEMPLARY, OR OTHER LOSSES, + COSTS, EXPENSES, OR DAMAGES ARISING OUT OF THIS PUBLIC LICENSE OR + USE OF THE LICENSED MATERIAL, EVEN IF THE LICENSOR HAS BEEN + ADVISED OF THE POSSIBILITY OF SUCH LOSSES, COSTS, EXPENSES, OR + DAMAGES. WHERE A LIMITATION OF LIABILITY IS NOT ALLOWED IN FULL OR + IN PART, THIS LIMITATION MAY NOT APPLY TO YOU. + + c. The disclaimer of warranties and limitation of liability provided + above shall be interpreted in a manner that, to the extent + possible, most closely approximates an absolute disclaimer and + waiver of all liability. + + +Section 6 -- Term and Termination. + + a. This Public License applies for the term of the Copyright and + Similar Rights licensed here. However, if You fail to comply with + this Public License, then Your rights under this Public License + terminate automatically. + + b. Where Your right to use the Licensed Material has terminated under + Section 6(a), it reinstates: + + 1. automatically as of the date the violation is cured, provided + it is cured within 30 days of Your discovery of the + violation; or + + 2. upon express reinstatement by the Licensor. + + For the avoidance of doubt, this Section 6(b) does not affect any + right the Licensor may have to seek remedies for Your violations + of this Public License. + + c. For the avoidance of doubt, the Licensor may also offer the + Licensed Material under separate terms or conditions or stop + distributing the Licensed Material at any time; however, doing so + will not terminate this Public License. + + d. Sections 1, 5, 6, 7, and 8 survive termination of this Public + License. + + +Section 7 -- Other Terms and Conditions. + + a. The Licensor shall not be bound by any additional or different + terms or conditions communicated by You unless expressly agreed. + + b. Any arrangements, understandings, or agreements regarding the + Licensed Material not stated herein are separate from and + independent of the terms and conditions of this Public License. + + +Section 8 -- Interpretation. + + a. For the avoidance of doubt, this Public License does not, and + shall not be interpreted to, reduce, limit, restrict, or impose + conditions on any use of the Licensed Material that could lawfully + be made without permission under this Public License. + + b. To the extent possible, if any provision of this Public License is + deemed unenforceable, it shall be automatically reformed to the + minimum extent necessary to make it enforceable. If the provision + cannot be reformed, it shall be severed from this Public License + without affecting the enforceability of the remaining terms and + conditions. + + c. No term or condition of this Public License will be waived and no + failure to comply consented to unless expressly agreed to by the + Licensor. + + d. Nothing in this Public License constitutes or may be interpreted + as a limitation upon, or waiver of, any privileges and immunities + that apply to the Licensor or You, including from the legal + processes of any jurisdiction or authority. + + +======================================================================= + +Creative Commons is not a party to its public +licenses. Notwithstanding, Creative Commons may elect to apply one of +its public licenses to material it publishes and in those instances +will be considered the “Licensor.” The text of the Creative Commons +public licenses is dedicated to the public domain under the CC0 Public +Domain Dedication. Except for the limited purpose of indicating that +material is shared under a Creative Commons public license or as +otherwise permitted by the Creative Commons policies published at +creativecommons.org/policies, Creative Commons does not authorize the +use of the trademark "Creative Commons" or any other trademark or logo +of Creative Commons without its prior written consent including, +without limitation, in connection with any unauthorized modifications +to any of its public licenses or any other arrangements, +understandings, or agreements concerning use of licensed material. For +the avoidance of doubt, this paragraph does not form part of the +public licenses. + +Creative Commons may be contacted at creativecommons.org. + diff --git a/README.md b/README.md index 04df21c..e33b4ef 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,72 @@ -# value-driven-analysis-and-design -Value Driven Analysis and Design (VDAD) +# Value-Driven Analysis and Design (VDAD) +[![CC BY 4.0][cc-by-shield]][cc-by] + +_TL;DR:_ Technology should support humanity and avoid harming people and their values; we want to help engineers and technology creators create solutions that promote positive values and aim to reduce harm to our society and people. The Value-Driven Analysis and Design (VDAD) process aims to combine value-driven approaches with state-of-the-art software engineering practices such as Domain-Driven Design (DDD). + +## Motivation and Vision + +Digitalized solutions generally try to optimize all kinds of processes, make people's work easier and achieve economic goals. While economic values already receive a lot of attention, it is often forgotten that digitalizing our world "wherever we can" has potentially negative effects on human values as well. + +The goal of this work is to enable all types of stakeholders in software-intensive projects to respect human/ethical values equally with economic and technical requirements throughout the life cycle of a project. + +We aim to achieve this by providing: + + 1. Lean and "audience-centric" processes and novel work practices. + 2. Knowledge structures, notation suggestions, and concrete examples. + 3. Recommendations for appropriate tools that support the suggested work practices. + +VDAD targets all roles and individuals engaged in digitalization projects. Every company or team engaged in the development of digital solutions has an influence on human beings, society, and our values. Technology creators who aspire to craft software and digital products that is both valuable and free from harm to humanity are invited to apply VDAD practices in their projects. + +The [user stories](user-stories.md) page outlines the target audience of VDAD with concrete, exemplary user stories. + +If you are interested in applying our practices in your projects, please [contact us](https://www.ost.ch/de/person/stefan-kapferer-2046). We are always happy to consult and/or collaborate on industry/research projects to see our ideas applied in the "real world" and to improve them based on the feedback collected. + +## Repository Content + +Value-Driven Analysis and Design (VDAD) describes an **iterative process** consisting of seven steps. Each step is described on a separate page and links to practices (activities and artifacts) along the process: + + * [Process Overview](./process/README.md) + * [Domain-Driven Practices and Collaborative Modelling as Enabler for Value-Based Engineering](./process/README.md#domain-driven-practices-and-collaborative-modelling-as-enabler-for-value-based-engineering) + * [Overview of Practices and Tools](./process/README.md#overview-of-practices-and-tools) + * [Step 1: Aquire Domain Understanding](./process/step-1-aquire-domain-understanding.md) + * [Step 2: Identify Stakeholders](./process/step-2-identify-stakeholders.md) + * [Step 3: Identify Values per Stakeholder](./process/step-3-identify-values-per-stakeholder.md) + * [Step 4: Prioritize Values](./process/step-4-prioritize-values.md) + * [Step 5: Make Digitalization Decision](./process/step-5-make-digitalization-decision.md) + * [Step 6: Derive New and Adjust Existing Requirements](./process/step-6-derive-new-and-adjust-existing-requirements.md) + * [Step 7: Design Software Architecture](./process/step-7-design-software-architecture.md) + * [Process Continuation (Iterative Approach)](./process/step-infinity-process-continuation.md) + +The [practices](./practices/README.md) folder contains the **practices supporting the VDAD process**: + + * [Stakeholder Modeling](./practices/stakeholder-mapping.md) + * [Value Impact Mapping](./practices/value-impact-mapping.md) + +**Additional files**: + + * [User Stories](user-stories.md) that describe exemplary VDAD application scenarios. + * Selected [Tools](tools.md) that support the VDAD process and our project. + * [Project Background and Related Work](related-work.md) + * [Glossary](glossary.md) + +## Contributing, Evaluation and Feedback +Any form of contribution is very welcome; please check [CONTRIBUTING.md](CONTRIBUTING.md) for contributions. + +We further welcome any feedback on our processes and practices. Use GitHub issues to get in touch or [contact us](https://www.ost.ch/de/person/stefan-kapferer-2046). We are also happy to discuss potential collaborations for research and industry projects. + +Contact: _[Stefan Kapferer](https://www.ost.ch/de/person/stefan-kapferer-2046), Eastern Switzerland University of Applied Sciences (OST)_ + +## Acknowledgments +Olaf Zimmermann and Mirko Stocker contributed to the VDAD repository content and related Context Mapper tooling via co-authoring, providing review feedback, experimentation and testing. Our shepherd for the EuroPLoP 2024 VDAD paper, as well as the attendees of the writer's workshop at the conference, provided valuable feedback on our proposed process pattern. Thank you all very much! + +Version 1.0 of VDAD has been supported by the [Institute for Software (IFS)](https://www.ost.ch/ifs) at the [Eastern Switzerland University of Applied Sciences (OST)](https://www.ost.ch). + +## License +This work is licensed under a +[Creative Commons Attribution 4.0 International License][cc-by]. + +[![CC BY 4.0][cc-by-image]][cc-by] + +[cc-by]: http://creativecommons.org/licenses/by/4.0/ +[cc-by-image]: https://i.creativecommons.org/l/by/4.0/88x31.png +[cc-by-shield]: https://img.shields.io/badge/License-CC%20BY%204.0-lightgrey.svg diff --git a/_config.yml b/_config.yml new file mode 100644 index 0000000..7f3b102 --- /dev/null +++ b/_config.yml @@ -0,0 +1,6 @@ +remote_theme: pages-themes/primer@v0.6.0 +plugins: +- jekyll-remote-theme + +title: [Value-Driven Analysis and Design (VDAD)] +description: [Technology should support humanity and avoid harming people and their values; we want to help engineers and technology creators create solutions that promote positive values and aim to reduce harm to our society and people. The Value-Driven Analysis and Design (VDAD) process aims to combine value-driven approaches with state-of-the-art software engineering practices such as Domain-Driven Design (DDD).] diff --git a/_layouts/default.html b/_layouts/default.html new file mode 100644 index 0000000..30adf8c --- /dev/null +++ b/_layouts/default.html @@ -0,0 +1,30 @@ + + + + + + + +{% seo %} + + {% include head-custom.html %} + + +
+ {% if site.title and site.title != page.title and page.url != "/" %} +

{{ site.title }}

+ {% endif %} + VDAD Process | Practices | Why VDAD? (User Stories) | Tools | Background | Glossary + + {{ content }} + + +
+ This work is open source and licensed under a Creative Commons Attribution 4.0 International License. Open on GitHub. +
+ +
+ + + + \ No newline at end of file diff --git a/future-work.md b/future-work.md new file mode 100644 index 0000000..aca3983 --- /dev/null +++ b/future-work.md @@ -0,0 +1,14 @@ +# Future Work + +This repository contains a version 1.0 of the Value-Driven Analysis and Design (VDAD) process and practices. We plan to further enhance and improve the project. + +This list represents current ideas how to further improve the initiative: + + * Extensions to (Domain-driven) practices for steps 4-6. + * Apply process in real projects to validate and improve it. + * This might lead to new patterns, practices and improvements to the process. + * Open up process and practices to management and strategic/business level. + * Monitoring of ethical issues in the long run. + * Many problems might only reveal themselves after years of productive experience wih a system. + +If you have ideas, feedback or want to discuss potential collaboration in projects, [please contact us](https://www.ost.ch/de/person/stefan-kapferer-2046). Also check our [CONTRIBUTING.md](CONTRIBUTING.md) in case you want to contribute to VDAD. diff --git a/glossary.md b/glossary.md new file mode 100644 index 0000000..a1b55be --- /dev/null +++ b/glossary.md @@ -0,0 +1,5 @@ +# Glossary + +Please refer to the [ESE glossary](https://github.com/ethical-se/ese-practices/blob/main/ESE-Glossary.md) and Clause 3 in IEEEE Standard 7000[^1] for the time being (the latter is available for free in IEEE Xplore, only a complimentary registration is required). + +[^1]: IEEE Standard Model Process for Addressing Ethical Concerns during System Design, 2021, https://ieeexplore.ieee.org/document/9536679 diff --git a/images/StakeholderMap-CM-generated.png b/images/StakeholderMap-CM-generated.png new file mode 100644 index 0000000..e425e2f Binary files /dev/null and b/images/StakeholderMap-CM-generated.png differ diff --git a/images/ValueImpactMap-CM-generated.png b/images/ValueImpactMap-CM-generated.png new file mode 100644 index 0000000..69df11f Binary files /dev/null and b/images/ValueImpactMap-CM-generated.png differ diff --git a/images/impact-mapping-sdd-example.jpg b/images/impact-mapping-sdd-example.jpg new file mode 100644 index 0000000..f5b6c4c Binary files /dev/null and b/images/impact-mapping-sdd-example.jpg differ diff --git a/images/impact-mapping-viz-template.jpg b/images/impact-mapping-viz-template.jpg new file mode 100644 index 0000000..f74072c Binary files /dev/null and b/images/impact-mapping-viz-template.jpg differ diff --git a/images/stakeholder-mapping-miro-template.png b/images/stakeholder-mapping-miro-template.png new file mode 100644 index 0000000..993358e Binary files /dev/null and b/images/stakeholder-mapping-miro-template.png differ diff --git a/images/stakeholder-mapping-sdd-example.jpg b/images/stakeholder-mapping-sdd-example.jpg new file mode 100644 index 0000000..8c9790d Binary files /dev/null and b/images/stakeholder-mapping-sdd-example.jpg differ diff --git a/images/vdad-process.jpg b/images/vdad-process.jpg new file mode 100644 index 0000000..8db9ab2 Binary files /dev/null and b/images/vdad-process.jpg differ diff --git a/models/meta-model.cml b/models/meta-model.cml new file mode 100644 index 0000000..a3352f7 --- /dev/null +++ b/models/meta-model.cml @@ -0,0 +1,74 @@ + +BoundedContext ValueDrivenAnalysisAndDesign { + + Module Common { + + Entity Bounded_Context { + -- "creates positive value or harm >" @EthicalValue + -- "has >" @ProjectStakeholder + + -- "implements >" @ArchitectureAndDesign + } + + Entity ProjectStakeholder { + String name; + - StakeholderType ^type; + + -- "is concerned by values >" @EthicalValue + -- "prioritizes values >" @StakeholderValuePriority + } + + enum StakeholderType { + VISIBLE, INVISIBLE; + } + + Entity EthicalValue { + -- "has different priority to different stakeholders >" @StakeholderValuePriority + } + + Entity PositiveValue extends EthicalValue { + + } + + Entity Harm extends EthicalValue { + + } + + ValueObject StakeholderValuePriority { + - ProjectStakeholder ^stakeholder; + - EthicalValue value; + - Priority ^priority; + } + + enum Priority { + H, M, L; + } + + Entity HarmMitigation { + String ^description; + - ProjectStakeholder ^stakeholder; + + -- "stakeholder requests mitigation for created harm >" @Harm + } + + Entity DigitalizationDecision { + - DecisionForm form; + - List ^values -- "values influencing decision"; + - List mitigations -- "planned mitigations" + } + + Entity NFR { + -- "are derived from defined mitigations >" @HarmMitigation + } + + Entity ArchitectureAndDesign { + -- "is influenced by NFRs derived from values >" @NFR + } + + enum DecisionForm { + ADR, Y_STATEMENT; + } + + } + +} diff --git a/models/meta-model_BC_ValueDrivenAnalysisAndDesign.png b/models/meta-model_BC_ValueDrivenAnalysisAndDesign.png new file mode 100644 index 0000000..3942add Binary files /dev/null and b/models/meta-model_BC_ValueDrivenAnalysisAndDesign.png differ diff --git a/models/meta-model_BC_ValueDrivenAnalysisAndDesign.puml b/models/meta-model_BC_ValueDrivenAnalysisAndDesign.puml new file mode 100644 index 0000000..f3cf7e2 --- /dev/null +++ b/models/meta-model_BC_ValueDrivenAnalysisAndDesign.puml @@ -0,0 +1,71 @@ +@startuml + +skinparam componentStyle uml2 + +package Common { + class Bounded_Context <<(E,DarkSeaGreen) Entity>> { + } + class Stakeholder <<(E,DarkSeaGreen) Entity>> { + String name + StakeholderType type + } + enum StakeholderType { + VISIBLE + INVISIBLE + } + class Value <<(E,DarkSeaGreen) Entity>> { + } + class PositiveValue <<(E,DarkSeaGreen) Entity>> { + } + class Harm <<(E,DarkSeaGreen) Entity>> { + } + class StakeholderValuePriority <<(V,DarkSeaGreen) Value Object>> { + Stakeholder stakeholder + Value value + Priority priority + } + enum Priority { + H + M + L + } + class HarmMitigation <<(E,DarkSeaGreen) Entity>> { + String description + Stakeholder stakeholder + } + class DigitalizationDecision <<(E,DarkSeaGreen) Entity>> { + DecisionForm form + List values + List mitigations + } + class NFR <<(E,DarkSeaGreen) Entity>> { + } + class ArchitectureAndDesign <<(E,DarkSeaGreen) Entity>> { + } + enum DecisionForm { + ADR + Y_STATEMENT + } +} +StakeholderValuePriority --> Value : value +Stakeholder --> StakeholderType : type +Bounded_Context -- Stakeholder : has > +NFR -- HarmMitigation : are derived from defined mitigations > +Value -- StakeholderValuePriority : has different priority to different stakeholders > +StakeholderValuePriority --> Stakeholder : stakeholder +DigitalizationDecision "1" o--> "*" HarmMitigation : planned mitigations +HarmMitigation -- Harm : stakeholder requests mitigation for created harm > +Bounded_Context -- ArchitectureAndDesign : implements > +Stakeholder -- Value : is concerned by values > +Bounded_Context -- Value : creates positive value or harm > +HarmMitigation --> Stakeholder : stakeholder +Stakeholder -- StakeholderValuePriority : prioritizes values > +StakeholderValuePriority --> Priority : priority +DigitalizationDecision "1" o--> "*" StakeholderValuePriority : values influencing decision +ArchitectureAndDesign -- NFR : is influenced by NFRs derived from values > +DigitalizationDecision --> DecisionForm : form +PositiveValue --|> Value +Harm --|> Value + + +@enduml diff --git a/models/meta-model_BC_ValueDrivenAnalysisAndDesign_Common.puml b/models/meta-model_BC_ValueDrivenAnalysisAndDesign_Common.puml new file mode 100644 index 0000000..f3cf7e2 --- /dev/null +++ b/models/meta-model_BC_ValueDrivenAnalysisAndDesign_Common.puml @@ -0,0 +1,71 @@ +@startuml + +skinparam componentStyle uml2 + +package Common { + class Bounded_Context <<(E,DarkSeaGreen) Entity>> { + } + class Stakeholder <<(E,DarkSeaGreen) Entity>> { + String name + StakeholderType type + } + enum StakeholderType { + VISIBLE + INVISIBLE + } + class Value <<(E,DarkSeaGreen) Entity>> { + } + class PositiveValue <<(E,DarkSeaGreen) Entity>> { + } + class Harm <<(E,DarkSeaGreen) Entity>> { + } + class StakeholderValuePriority <<(V,DarkSeaGreen) Value Object>> { + Stakeholder stakeholder + Value value + Priority priority + } + enum Priority { + H + M + L + } + class HarmMitigation <<(E,DarkSeaGreen) Entity>> { + String description + Stakeholder stakeholder + } + class DigitalizationDecision <<(E,DarkSeaGreen) Entity>> { + DecisionForm form + List values + List mitigations + } + class NFR <<(E,DarkSeaGreen) Entity>> { + } + class ArchitectureAndDesign <<(E,DarkSeaGreen) Entity>> { + } + enum DecisionForm { + ADR + Y_STATEMENT + } +} +StakeholderValuePriority --> Value : value +Stakeholder --> StakeholderType : type +Bounded_Context -- Stakeholder : has > +NFR -- HarmMitigation : are derived from defined mitigations > +Value -- StakeholderValuePriority : has different priority to different stakeholders > +StakeholderValuePriority --> Stakeholder : stakeholder +DigitalizationDecision "1" o--> "*" HarmMitigation : planned mitigations +HarmMitigation -- Harm : stakeholder requests mitigation for created harm > +Bounded_Context -- ArchitectureAndDesign : implements > +Stakeholder -- Value : is concerned by values > +Bounded_Context -- Value : creates positive value or harm > +HarmMitigation --> Stakeholder : stakeholder +Stakeholder -- StakeholderValuePriority : prioritizes values > +StakeholderValuePriority --> Priority : priority +DigitalizationDecision "1" o--> "*" StakeholderValuePriority : values influencing decision +ArchitectureAndDesign -- NFR : is influenced by NFRs derived from values > +DigitalizationDecision --> DecisionForm : form +PositiveValue --|> Value +Harm --|> Value + + +@enduml diff --git a/practices/README.md b/practices/README.md new file mode 100644 index 0000000..6567025 --- /dev/null +++ b/practices/README.md @@ -0,0 +1,10 @@ +# VDAD Practices + +This folder contains all new (suggested by us) or adjusted (existing) practices supporting the VDAD process. Currently, there are two: + + * [Stakeholder Mapping](stakeholder-mapping.md) (documented for the specific use case; not a new practice) + * [Value Impact Mapping (VIM)](value-impact-mapping.md) + +For all other existing practices that support the VDAD process, we refer to the [practices table in the process overview page](./../process/README.md#overview-of-practices-and-tools). + +For tools that support and ease the application of our practices, please check the [tools page](./../tools.md). diff --git a/practices/stakeholder-mapping.md b/practices/stakeholder-mapping.md new file mode 100644 index 0000000..77d9e23 --- /dev/null +++ b/practices/stakeholder-mapping.md @@ -0,0 +1,114 @@ +# Practice: Stakeholder Mapping + +_Note:_ **This practice is not invented by us!** The Stakeholder Mapping practice has already been around for a while, several related approaches and templates have been proposed [^1][^2][^3]. + +This practice is covered here as well for the sake of completeness: if you want to create a [Value Impact Mapping](./value-impact-mapping.md) or go through the whole [Value-Driven Analysis and Design (VDAD)](./../value-driven-analysis-and-design) process, this practice can help you to identify your stakeholders first. The following instructions and explanations of this practice are however specific to the context of ethical or "value-driven" analysis goals. + +## Context +A group of people, may it be managers, engineers, people who want to build a new startup company, etc., want to produce some new piece of software. They want to find out who their stakeholders are and what the impact of the system to be built is on those stakeholders. In our context here, they probably want to apply [Value Impact Mapping](./value-impact-mapping.md) and need to know the stakeholders in advance (precondition). + +The following inputs (see [VDAD's Step 1](./../process/step-1-aquire-domain-understanding.md)) are helpful for this practice: + + * Knowledge about the domain of the system (for example in the form of a domain model) + * Workflows that illustrate business processes, elicited with domain-driven practices such as Event Storming[^2] or Domain Storytelling[^3] + * Use Cases and/or User Stories, as summarized in Design Practice Repository (DPR)[^4] + * Already known Non-Functional Requirements (NFRs) and technical/organizational constraints + * Additional artifacts depending on project context and needs + +## Goal +The goal of this practice is not only to find stakeholders that are _directly_ affected by the system (such as users), but to identify _indirect_ stakeholders as well. Indirect stakeholders can be other organisations, the government, or individuals; anyone that will somehow be affected by the system, even when not directly using it. Literature on this topic often also refers to _visible_ (direct) vs. _invisible_ (indirect) stakeholders. As already mentioned, invisible stakeholders are human beings that are not directly involved in your project; for example, if you start a new online shopping business, invisible stakeholders could be local stores that you maybe do not know but whose business model is threatened by your new digital system. + +## Procedure / Instructions +It is typically easier to start identifying visible/direct stakeholders. These can usually just be derived from the conducted functional requirements. You find them in: + + * Use Cases (Actors) + * User Stories ("As a ..." part of stories) + * Domain Models + * Event Stormings / Domain Storytellings (Actors) + * etc. + +Some stakeholders might have same interests or belong to a common group of stakeholders. For example, a "product manager" and the "board of directors" could both be subordinated to a group called "management". This way, you can structure your stakeholder hierarchically and make your stakeholder map clearer and easier to read. + +In a second step, chances are high that this is more tricky, you have to anticipate invisible/indirect stakeholders. It might help to: + + * Go through the complete business process; which human beings are not part of the process but still affected? + * Which existing processes does the system or feature you are going to build change/adjust? Are there human beings that are affected by these existing processes? + * Consult existing stakeholder classifications[^4]; these might contain stakeholder groups you haven't thought of. + * Potentially already think about values that are affected by your system. For example by studying the overarching core values of the IEEE 7000 standard[^5]. This can help in uncovering invisible stakeholders as well. + +## Notations + +### Graphical Notation + +There are several graphical notations (see references) available that can be created used with graphical tools such as [Miro](https://miro.com/). + +The following example uses [this template](https://miro.com/de/templates/stakeholder-map/) for Miro and allows to group the stakeholders: + +![Miro Stakeholder Mapping Template](./../images/stakeholder-mapping-miro-template.png) + +### Context Mapper DSL + +[Context Mapper](https://contextmapper.org/) with its Context Mapping DSL (CML) language offers a Domain-Specific Language (DSL) to model stakeholders. Context Mapper is available as a [Visual Studio Code Extension](https://contextmapper.org/docs/vs-code/), as an [Eclipse Plugin](https://contextmapper.org/docs/eclipse/), or alternatively available as [Online IDE via Gitpod](https://contextmapper.org/docs/online-ide/). With CML you can simply model stakeholders in textual form and generate the graphical diagram with its PlantUML generator. + +The following example illustrates how stakeholders and stakeholder groups can easily be modelled in CML. Checkout the [Context Mapper documentation on stakeholder modelling](https://contextmapper.org/docs/stakeholders/) for more details and complete documentation. + +```cml +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 + } + +} +``` + +## Examples +In the following, a fictitious online shop scenario is used to illustrate this practice. An existing online shopping company wants to realize a new offering for "same day delivery". Customers in emergency situations shall be able to order everyday products and get them delivered on the same day. + +The team has identified visible stakeholders such as _Shoppers_, the _Development Team_ and the _Product Management_ as well as invisible stakeholders such as the _Drivers of Delivery Partners_ and _Competing Companies_. They have first visualized their stakeholders for the new shop feature vizually with [Miro](https://miro.com): + +![Stakeholder Map Example: Same Day Delivery Online Shop Scenario](./../images/stakeholder-mapping-sdd-example.jpg) + +Alternatively, the team tried to model the same outcome in the Context Mapper DSL as introduced above. By using Context Mappers's PlantUML generator, it is possible to generate the [Stakeholder Map](./../practices/stakeholder-mapping.md) automatically: + +![Exemplary Stakeholder Map generated with Context Mapper](./../images/StakeholderMap-CM-generated.png) + +The Freemarker template used by Context Mapper is publicly available, just like the source code of the tool. Therefore, it is possible to extend it according to individual preferences and projects needs (just in case you miss the colors used in the previous example). + +## Tools +Stakeholders can be documented with various tools: + + * Visual tools such as [Miro](https://miro.com) + * [Context Mapper's features supporting VDAD](https://contextmapper.org/docs/vdad-support) + * Textual editors + +## Related Practices +Stakeholder Mapping is a well-known practice and promoted by several tools[^1][^2][^3]. Additionally, the practice of identifying stakeholders is of course part of other ethical approaches in engineering as well, such as the IEEE 7000 standard[^5] or Value-Based Engineering[^6]. These standards and books might further help and contain more detailed advice in case you want to dig deeper. Our practice [Value Impact Mapping (VIM)](value-impact-mapping.md) is related as it needs stakeholders as well and is part of the subsequent VDAD step; Stakeholder Mapping supports [Step 2](./../process/step-2-identify-stakeholders.md), while [Value Impact Mapping (VIM)](value-impact-mapping.md) can be used for [Step 3](./../process/step-3-identify-values-per-stakeholder.md). + + +[^1]: +[^2]: +[^3]: +[^4]: _Ethics in Software Engineering: A Systematic Literature Review_, Razieh Alidoosti, Patricia Lago, Maryam Razavian, Antony Tang, https://hdl.handle.net/1871.1/6babced3-4bd2-443e-8c1b-b0593a4cb6e1 +[^5]: IEEE Standard Model Process for Addressing Ethical Concerns during System Design, 2021, +[^6]: Value-Based Engineering - A Guide to Building Ethical Technology for Humanity, Sarah Spiekermann, 2023, diff --git a/practices/template.md b/practices/template.md new file mode 100644 index 0000000..2a6db1f --- /dev/null +++ b/practices/template.md @@ -0,0 +1,22 @@ +# Practice: {name} + +## Context +In which situation does the practice help? Which input does it work with? + +## Goal +What is the goal of the practice? What should be the output/outcome? + +## Procedure / Instructions +Step-by-step instructions how the practice shall be applied ... + +## Notations +Different notations/visualizations that can be used. + +## Examples +Concrete application examples. + +## Tools +Which tools can support practitioners of this practice? + +## Related Content +Related practices, methods, tools, etc. diff --git a/practices/value-impact-mapping.md b/practices/value-impact-mapping.md new file mode 100644 index 0000000..54a1a3a --- /dev/null +++ b/practices/value-impact-mapping.md @@ -0,0 +1,159 @@ +# Practice: Value Impact Mapping + +_Hint:_ This practice is inspired by the more general planning technique [Impact Mapping](https://www.impactmapping.org/). We adjusted it specifically for the needs of identifying positive and negative impact on human being's values. + +## Context +There are varying starting positions from which a group of people might want to think about the impact of some piece of technology they are aiming to build. Such starting positions can be: + + * A group of people, technical (engineers) or not, who want to found a startup company and build a new software product. + * A technology company that considers building a new product. + * A software development team that has to implement a new feature for an existing product. + +Value Impact Mapping (VIM) is eligible whenever some technology like software, that is used by people and has impact on people, shall be created or adjusted. + +_Precondition:_ We assume that the direct and indirect stakeholders of the system or feature to be built have already been identified. If this is not the case, a stakeholder analysis should be conducted, for instance leveraging the [Stakeholder Mapping](./stakeholder-mapping.md) practice. + +## Goal +The goal of this practice is to identify all stakeholder's values that might be affected by the system or feature. The impact on such values might be positive, neutral, or negative. Examples for ethical values applicable to system design are _autonomy_, _fairness_, _privacy_, _respect_, etc. Systems can promote or harm such values for stakeholders. For a deeper understanding regarding what values are, have a look at the IEEE 7000 Standard[^1] or the introduction video [What are Values](https://www.youtube.com/watch?v=aYqCmmkrguI) by Sarah Spiekermann. A set of common ethical values is provided in Annex G of IEEE 7000, which is positioned as suggestive but not normative. + +In addition to identifying the values, a goal of this practice is to find potential mitigation actions for negatively impacted values. + +## Procedure / Instructions + +*First, "what" and "which "questions have to be answered:* + +### Identify values per stakeholder, and the positive and negative impact of the system or feature on these values. + +Ask the following questions _for each_ stakeholder in order to identify their values and the impact of the system or feature towards those values: + + * Which benefits does the system provide for the individual stakeholder if the system were implemented at scale? + * Which harms could be caused for the individual stakeholder if the system were implemented at scale? + * What are the negative implications of the system or feature for the character and personality of the individual stakeholder? + * Which values and virtues would you consider as so important in terms of your personal maxims that you would want their protection to be recognized as a universal law and that should therefore be respected by the system or feature? + +_References:_ These questions come from the IEEE 7000 Standard[^1] and Value-Based Engineering (VBE)[^2]; they are based on the three ethical frameworks _virtue ethics_, _duty ethics_, and _utilitarianism_. + +Ideally, you answer the questions and identify the values together with stakeholder representatives. Conduct interviews with them and find out what is important to them. In case a direct conversation is not possible, you could create Personas. + +The Proctive Consider, Analyze, Review, Evaluate (CARE) framework[^3] and Software Development Impact Statements (SoDIS)[^4] as well as the Consequence Scanning[^5] also provide questions to ask when prioritizing values and assessing impact. + +*In a second step, "how" questions look at dealing with values and their impact:* + +### Find potential improvements to the system that reduce harm (mitigation actions). + +For each harmed value identified in the previous step, think about whether there could be mitigation actions. + + * Are there possible adjustments and/or extensions to the feature or system characteristic that can be implemented so that the respecting value is less harmed? + * Are there parts of the feature or system that maybe should not be built? + +Together with your stakeholders, try to find adjusted solutions that still fulfill your (non-)functional requirements, but do not harm the identified values as much as the solution you had in mind before. This can also mean that you agree that some features should not be implemented. + +## Notations + +### Graphical Notation + +Inspired by the [Impact Mapping](https://www.impactmapping.org/) practice, we suggest to use a mind map, structured into four levels (feature-stakeholder-values-actions): + +![Value Impact Map Structure Template](./../images/impact-mapping-viz-template.jpg) + +The four levels are: + + 1. The *feature* or system characteristic you want to analyze. + 2. The impacted *stakeholders*. + 3. The *values* of the individual stakeholders; including an indication whether the value is fostered or harmed. + 4. Mitigation *actions* which can be taken in order to reduce harm. + +You can create Value Impact Maps physically on the whiteboard or with any graphical tool that supports mind maps. For example, [Miro](https://miro.com) provides a template: [Miro Impact Mapping template](https://miro.com/templates/impact-mapping/). + +### Context Mapper DSL + +[Context Mapper](https://contextmapper.org/) with its Context Mapping DSL (CML) language offers a Domain-Specific Language (DSL) to model stakeholders and their values. Context Mapper is available as a [Visual Studio Code Extension](https://contextmapper.org/docs/vs-code/), as an [Eclipse Plugin](https://contextmapper.org/docs/eclipse/), or alternatively available as [Online IDE via Gitpod](https://contextmapper.org/docs/online-ide/). With CML you can simply model stakeholders and value registers in textual form and then generate a Value Impact Map with its PlantUML generator automatically. + +The following example illustrates how values in value registers[^1] can easily be modelled in CML. Checkout the [Context Mapper documentation on value register modeling](https://contextmapper.org/docs/value-registers/) for more details and complete documentation. + +```cml +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" + } + } +} +``` + +## Example + +To illustrate this practice, we use a fictitious online shop scenario. An existing online shopping company wants to realize a new offering for "same day delivery". Customers in emergency situations shall be able to order everyday products and get them delivered on the same day. + +The company already identified the stakeholder groups and stakeholders by creating a [Stakeholder Map](./stakeholder-mapping.md): + +![Same Day Delivery Shop - Stakeholder Map Example](./../images/stakeholder-mapping-sdd-example.jpg) + +Now, they elicit the values of these stakeholders and identify benefits and harms towards those values. The following exemplary Value Impact Map is not complete (it does not cover all stakeholders); it shall just illustrate how such a map could look like. + +The team identified the following benefits and harms (top-down order as in the map below): + +![Same Day Delivery Shop - Value Impact Map Example](./../images/impact-mapping-sdd-example.jpg) + + * The feature might **increase the freedom for shoppers** in certain cases; they do not need to leave their home and rush to a shop in an emergency scenario (imagine you have your kids at home and cannot easy leave but need an every day article urgently). + * The feature **harms sustainability**, potentially in multiple forms: + * More delivery trucks will have to be on the road in order to implement this feature (**environmental** sustainability). + * If customers get used to the feature, they will potentially start using it for non-emergency cases as well and get used to not leaving the house at all. Social interactions are reduced, etc. (sustainability in terms of **physical as well as psychological health**). + * A benefit of the feature, according to the management, shall be the fact that **"quality of life" is increased** in such emergency situations. The feature shall **reduce stress** for the human being in the emergency. + * On the other hand, the feature potentially **harms the patience** of customers. A development of our society today is that everything goes faster and faster ... The same day delivery feature fosters that development. Once used to getting an article delivered on the same day, people might get more annoyed if this is not the case (changed expectations). + * For the delivery staff this feature could lead to increased workload, new working shifts, and therefore **harmed work-life balance**. + * The online shop company wants to have the feature because the expect **benefits in revenue** as it will attract more customers. + +*Note:* This list does not claim to be complete; you might come up with other benefits and harms for this specific scenario. + +Once the company identified the values (column 3 in Value Impact Map above), they added mitigation actions that could reduce the harm to some values: + + * Harm to sustainability could be reduced by **limiting the availability** of the feature. Same day delivery could for example only be available for certain products or only in case it would not mean one single truck driving for just that single article. + * The feature could be **optional and not the "default"**. With the price of this delivery, the company could ensure that users not use it every time - but just in emergency situations (setting the right incentives). + * If the delivery stuff is no longer able to handle orders, the system could temporarily disable the feature in order to **protect employees work-life balance**. + * etc. + +Again, this list of mitigation actions is not complete. You might come up with others. + +Alternatively, the values could have been modeled with the [Context Mapper](https://contextmapper.org) CML language, as introduced above. With its PlantUML generator, the Value Impact Map would be automatically generated as follows: + +![Exemplary Value Impact Map generated with Context Mapper](./../images/ValueImpactMap-CM-generated.png) + +## Tools +Value Impact Maps can be created with various tools: + + * Graphical tools that support mind mapping; such as [Miro](https://miro.com). + * Context Mapper with its ability to [model stakeholders and values](/docs/vdad-support/) and then generate a Value Impact Map automatically. + +## Related Practices + +There are alternative and related practices/techniques to achieve the goal of producing valuable, ethically responsible software: + + * The IEEE 7000 standard[^1] offers an extensive process that goes way deeper into the topic. It is however not that "lightweight" as our suggested approaches or as ESE (see next bullet). + * [Ethical Software Engineering (ESE)](https://github.com/ethical-se/ese-practices) applies the IEEE 7000 standard to agile practices. For example, the practice [Story Valuation](https://github.com/ethical-se/ese-practices/blob/main/practices/ESE-StoryValuation.md) can be seen as alternative approach to Value Impact Mapping that is applied to User Stories. + * Value-Based Engineering[^2] by Sarah Spiekermann is another interesting approach which also inspired us and has many similarities to the IEEE 7000 standard. + +Our [Stakeholder Mapping](stakeholder-mapping.md) practice is of course related as well, as both require stakeholders and are used in subsequent steps of the VDAD process; Stakeholder Mapping supports [Step 2](./../process/step-2-identify-stakeholders.md), while [Value Impact Mapping (VIM)](value-impact-mapping.md) can be used for [Step 3](./../process/step-3-identify-values-per-stakeholder.md). + + +[^1]: IEEE Standard Model Process for Addressing Ethical Concerns during System Design, 2021, +[^2]: Value-Based Engineering - A Guide to Building Ethical Technology for Humanity, Sarah Spiekermann, 2023, +[^3]: Proctive Consider, Analyze, Review, Evaluate (CARE), +[^4]: Software Development Impact Statements (SoDIS), +[^5]: Consequence Scanning, diff --git a/process/README.md b/process/README.md new file mode 100644 index 0000000..a3fd838 --- /dev/null +++ b/process/README.md @@ -0,0 +1,46 @@ +# Value-Driven Analysis and Design (VDAD) Process Overview + +VDAD, first presented at EuroPLoP 2024[^3], combines value-driven approaches with analysis and design practices in software engineering; we especially aim at bringing ethical thinking into domain-driven practices. As software engineers, we should build digitalized solutions that serve humanity - never the other way around. VDAD proposes seven steps that cover the whole development lifecycle and aim at illustrating how human and ethical values can be respected in all phases of the software development process. + +The seven steps are: + + * **Step 1:** [Aquire Domain Understanding](./step-1-aquire-domain-understanding.md) + * **Step 2:** [Identify Stakeholders](./step-2-identify-stakeholders.md) + * **Step 3:** [Identify Values per Stakeholder](./step-3-identify-values-per-stakeholder.md) + * **Step 4:** [Prioritize Values](./step-4-prioritize-values.md) + * **Step 5:** [Make Digitalization Decision](./step-5-make-digitalization-decision.md) + * **Step 6:** [Derive New and Adjust Existing Requirements](./step-6-derive-new-and-adjust-existing-requirements.md) + * **Step 7:** [Design Software Architecture](./step-7-design-software-architecture.md) + +*Note:* The VDAD process is not considered to be conducted in a linear, unidirectional way. Project teams have to iterate over the individual steps as well as the whole process. The page [process continuation](step-infinity-process-continuation.md) explains this incremental approach. + +The following illustration visualizes the VDAD process with its steps as well as the input and output artifacts of the individual steps. + +![Value-Driven Analysis and Design (VDAD) Process](./../images/vdad-process.jpg) + +_Note:_ Each step with its inputs and outputs is elaborated in detail on the corresponding pages linked above. + +## Domain-Driven Practices and Collaborative Modelling as Enablers +All value-driven approaches and processes that aim at treating values as first-class citizens (such as the IEEE-7000[^2] or Value-Based Engineering[^1]) require close and interdisciplinary collaboration between all stakeholders and human beings affected by a system. + +One important goal of Domain-Driven Design (DDD) and Collaborative Modelling approaches (such as Event Storming, Domain Storytelling, etc.) is to find a common understanding and a ubiquitous language between engineers, domain experts, and any other stakeholders. Therefore, these practices and methods can help us in applying value-based engineering and establish the required communication between all human being involved in the process. + +Modelling in general can help us to visualize the context of a system, interrelations between stakeholders and values, and conflicts that should be identified so that they can, hopefully, be solved. + +## Overview of Practices and Tools +The following overview lists all practices and artifacts that support you in the individual VDAD steps: + +| VDAD Step | Practices and Artifacts | +|---------------------------------------------------------|-------------------------| +| **Step 1**: Aquire Domain Understanding | Use Cases, User Stories, Business Process Models, Domain Models (e.g. with [Context Mapper](https://contextmapper.org)) based on Domain-Driven Design (DDD) patterns, [Collaborative Modelling](https://www.wps.de/aktuelles/collaborative-modelling) (e.g. Event Storming, Domain Storytelling) | +| **Step 2**: Identify Stakeholders | [Stakeholder Mapping](./../practices/stakeholder-mapping.md), Personas, Identify them in the artifacts produced in _Step 1_ (Use Cases, User Stories, etc.), Context Mapper DSL (CML) stakeholder model | +| **Step 3**: Identify Values per Stakeholder | [Stakeholder Mapping](./../practices/stakeholder-mapping.md) and [Value Impact Mapping (VIM)](./../practices/value-impact-mapping.md), Value Register[^2], [ESE](https://github.com/ethical-se/ese-practices) templates to model values, Context Mapper DSL (CML) value model | +| **Step 4**: Prioritize Values | Value Register[^2], templates suggested in [ESE Story Valuation](https://github.com/ethical-se/ese-practices/blob/main/practices/ESE-StoryValuation.md), Context Mapper DSL (CML) value model with stakeholder priorities | +| **Step 5**: Make Digitalization Decision | _All inputs from steps before_ | +| **Step 6**: Derive New and Adjust Existing Requirements | Use models and knowledge from previous steps to elicit and/or refine functional and non-functional requirements; formulate so-called Ethical Value Requirement (EVRs) according IEEE 7000 standard[^2], apply [ESE Story Valuation](https://github.com/ethical-se/ese-practices/blob/main/practices/ESE-StoryValuation.md) to create EVRs | +| **Step 7**: Design Software Architecture | [Architecture Decision Records (ADRs)](https://adr.github.io/), architecture documentation (e.g. filled-out [arc42](https://www.arc42.de/) template), Strategic and Tactic DDD (i.e., Bounded Contexts and Domain Models with Aggregates, Entities and other DDD patterns); use [Context Mapper](https://contextmapper.org) for modelling) for architecture and design, working software | + + +[^1]: https://www.value-based-engineering.com/ +[^2]: IEEE Standard Model Process for Addressing Ethical Concerns during System Design, 2021, +[^3]: _Published EuroPLoP paper coming soon ..._ diff --git a/process/step-1-aquire-domain-understanding.md b/process/step-1-aquire-domain-understanding.md new file mode 100644 index 0000000..3a33ec8 --- /dev/null +++ b/process/step-1-aquire-domain-understanding.md @@ -0,0 +1,37 @@ +# VDAD Step 1: Aquire Domain Understanding + +_TL;DR:_ Apply domain-driven practices to analyze the domain with its core, generic and supporting subdomains[^1] and acquire knowledge about them. Establish a common vocabulary, the Ubiquituous Language[^1] of the domain. + +## Goal and Approach +This step ideally involves all project stakeholders from customers, business experts, users to developers. The goal of this first step is to aquire a common understanding between business people and developers/engineers. A common language shall be spoken so that misunderstandings and the need for translation are reduced. + +This step usually, at least in the first iterations, produces analysis results on a higher level. A Domain Model must, therefore, not already use [tactic DDD](https://socadk.github.io/design-practice-repository/activities/DPR-TacticDDD.html) patterns and is not ready to be implemented. An Event Storming[^2] or Domain Storytelling[^3] can also be considered a viable alternative to a Domain Model at this stage. It is just important that you model the established understanding. In domain-driven terms: you probably model the real world - as it is - in this step; meaning you are modelling Subdomains (object-oriented analysis), but not Bounded Contexts yet (object-oriented design). + +### Inputs +The domain knowledge of the experts and existing business processes are the input to this step. + +### Outputs +The knowledge is written down and carved into: + + * A Domain Model, potentially per Subdomain[^1] or already per Bounded Context[^1] (but not necessarily in the first iteration) + * Workflows that illustrate business processes, elicited with domain-driven practices such as Event Storming[^2] or Domain Storytelling[^3] + * Use Cases and/or User Stories, as summarized in the Design Practice Repository (DPR)[^4] + * Already known Non-Functional Requirements (NFRs) and technical/organizational constraints + * Additional artifacts depending on project context and needs + +## Supporting Tools + + * [Egon.io](https://egon.io/) for Domain Storytelling[^3] + * Whiteboards or digital tools such as [Miro](https://miro.com/) for Event Stormings[^2] + * [Context Mapper](https://contextmapper.org) for domain modelling, use cases, user stories + +## Process Navigation + + * [Complete VDAD Process](./../value-driven-analysis-and-design) + * [Next Step (2): Identify Stakeholders](./step-2-identify-stakeholders.md) + + +[^1]: _Domain-Driven Design Reference_, Eric Evans, +[^2]: +[^3]: _Domain Storytelling: A Collaborative, Visual, and Agile Way to Build Domain-Driven Software_, Stefan Hofer, Henning Schwentner, +[^4]: _Design Practice Repository (DPR)_, Olaf Zimmermann and Mirko Stocker, diff --git a/process/step-2-identify-stakeholders.md b/process/step-2-identify-stakeholders.md new file mode 100644 index 0000000..ce9714f --- /dev/null +++ b/process/step-2-identify-stakeholders.md @@ -0,0 +1,35 @@ +# VDAD Step 2: Identify Stakeholders + +_TL;DR:_ Recognize all (visible and invisible) stakeholders. + +## Goal and Approach +The goal of this second step is to identify all stakeholders (visible and invisible) of the system or feature; meaning all human beings that are somehow affected by the system. A challenge in this step is the identification of _invisible stakeholders_ – stakeholders that do not directly interact with the system. Visible stakeholders are usually already identified when conducting functional requirements with User Stories or Use Cases. Identifying invisible stakeholders means anticipating who might be indirectly affected by the system. Consulting existing stakeholder classifications[^1] might help not forgetting important stakeholder groups. + +We recommend applying the [Stakeholder Mapping](./../practices/stakeholder-mapping.md) practice. + +### Inputs +The outputs of [Step 1](./step-1-aquire-domain-understanding.md) (such as Use Cases, User Stories, Domain Models, etc.) can be used as inputs to this step, as for example actors in Use Cases or in the "As a ..." part of User Stories are visible stakeholders. Domain Storytelling[^2] or Event Storming[^3] can provide hints as well. + +### Outputs +The output of this step should be a compilation of all identified stakeholders. This can be: + + * A list of all stakeholders in textual form + * A stakeholder map, as a result of the [Stakeholder Mapping](./../practices/stakeholder-mapping.md) practice + +**Note**: In case a stakeholder group of yours is huge (for example all shoppers that use an online shop; potentially many human beings) and you are not able to directly communicate with a representative of this group, consider creating Personas[^4] for these cases as an additional output of this step. + +## Supporting Tools + +Stakeholders can be written down textually or documented visually with tools such as [Miro](https://miro.com). The [Context Mapper](https://contextmapper.org) tools allows you to model your stakeholders together with your domain, user stories, etc. You can further generate [Stakeholder Maps](./../practices/stakeholder-mapping.md) automatically with [Context Mapper](https://contextmapper.org) (more details on the [Stakeholder Mapping](./../practices/stakeholder-mapping.md) practice page). + +## Process Navigation + + * [Complete VDAD Process](./../value-driven-analysis-and-design) + * [Previous step: Aquire Domain Understanding](./step-1-aquire-domain-understanding.md) + * [Next step: Identify Values per Stakeholder](./step-3-identify-values-per-stakeholder.md) + + +[^1]: _Ethics in Software Engineering: A Systematic Literature Review_, Razieh Alidoosti, Patricia Lago, Maryam Razavian, Antony Tang, +[^2]: _Domain Storytelling: A Collaborative, Visual, and Agile Way to Build Domain-Driven Software_, Stefan Hofer, Henning Schwentner, 2021, +[^3]: +[^4]: diff --git a/process/step-3-identify-values-per-stakeholder.md b/process/step-3-identify-values-per-stakeholder.md new file mode 100644 index 0000000..be8df49 --- /dev/null +++ b/process/step-3-identify-values-per-stakeholder.md @@ -0,0 +1,46 @@ +# VDAD Step 3: Identify Values per Stakeholder + +_TL;DR:_ Elicit the individual values of the identified stakeholders. Consolidate this information to create and populate a value register progressively. + +## Goal and Approach +After having identified the stakeholders in [Step 2](./step-2-identify-stakeholders.md), the goal of this step is to identify the values that are important to the stakeholders and stakeholder groups. + +This should ideally be done in direct communication with the affected people. In case this is not possible, it requires an empathic "putting yourself in the perspective of the people affected" approach. + +Apply the [Value Impact Mapping](./../practices/value-impact-mapping.md) practice suggested in this repository to identify all stakeholder's values that might be affected by the system or feature. The impact on such values might be positive, neutral, or negative. + +You might wan to create *value models*, for instance with a tool such as [Context Mapper](https://contextmapper.org). Context Mapper supports the [modelling of stakeholders and their values](https://contextmapper.org/docs/vdad-support). Value models express important values are to stakeholders and what the impact of a system or feature to those stakeholders and their values is. + +As an alternative to value models and/or [Value Impact Maps](./../practices/value-impact-mapping.md), create a full-fledged value register[^2] as specified in IEEE 7000 standard[^1]. Such a value register contains all important values of the stakeholders and how the system or feature positively or negatively impacts these values as well. ESE practices[^3] such as Story Valuation and the value notations suggested in ESE can further support the creation of the value register; [Context Mapper](https://contextmapper.org) supports the modelling of value registers and the terminology of the IEEE 7000 standard[^1] as well. + +### Inputs +The identified stakeholders of [Step 2](./step-2-identify-stakeholders.md), especially the outcome of applying the [Stakeholder Mapping](./../practices/stakeholder-mapping.md) practice, are the input to this step. + +### Outputs +This step of the VDAD process shall produce the necessary knowledge about the stakeholders values. This knowledge can be documented in various forms: + + * [Value Impact Maps](./../practices/value-impact-mapping.md) + * Value models created with [Context Mapper](https://contextmapper.org) + * Value Registers[^2][^1], for example using ESE notations[^3] + * Optionally: Already think about mitigation actions that could be taken into account to reduce negative impact (harm) on values. + * [Context Mapper](https://contextmapper.org) also allows you to model such mitigation actions and adds it to the generated [Value Impact Map](./../practices/value-impact-mapping.md). + * These considerations will help in [Step 6](step-6-derive-new-and-adjust-existing-requirements.md) as they might lead to adjusted or new requirements towards your system or feature. + +Besides the gained knowledge about the values of the stakeholders, this VDAD step should reveal potential conflicts. + +## Supporting Tools + +The [Context Mapper](https://contextmapper.org) tool supports the [modelling of stakeholders and values](https://contextmapper.org/docs/vdad-support) with its CML language. You can then automatically generate a [Value Impact Map (VIM)](./../practices/value-impact-mapping.md) (more details on the [Value Impact Mapping](./../practices/value-impact-mapping.md) practice page). + +Alternatively, you can use other textual or visual tools. ESE provides alternative notations for maintaining value registers.[^3] + +## Process Navigation + + * [Complete VDAD Process](./../value-driven-analysis-and-design) + * [Previous step: Identify Values per Stakeholder](./step-3-identify-values-per-stakeholder.md) + * [Next step: Prioritize Values](./step-4-prioritize-values.md) + + +[^1]: IEEE Standard Model Process for Addressing Ethical Concerns during System Design, 2021, +[^2]: "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." +[^3]: diff --git a/process/step-4-prioritize-values.md b/process/step-4-prioritize-values.md new file mode 100644 index 0000000..1e138c8 --- /dev/null +++ b/process/step-4-prioritize-values.md @@ -0,0 +1,36 @@ +# VDAD Step 4: Prioritize Values + +_TL;DR:_ Prioritize the conflicts and values identified so far. Identify the most important values for the team and where it is possible to compromise. Start and follow a requirements prioritization and tradeoff management process that involves all stakeholders. + +## Goal and Approach +This VDAD step is both critical and challenging. Values and consequences might need to be analyzed in more depth. Stakeholders have different values and conflicts cannot be avoided. There are opposing values; for example, _privacy_ might require to hide certain data while _transparency_ calls for making it visible. + +The objective of this phase is to facilitate consensus among the project team regarding the prioritization of values and the resolution of conflicts. This process hinges on effective communication and the willingness to compromise. + +Modifications to the features or system requirements may be beneficial in the mitigation of potential harm to values that are of importance to stakeholders. The identification of adjusted solutions with which all stakeholders can live may therefore assist in the resolution of conflicts between people. + +Furthermore, decomposing the systems into bounded contexts according to Domain-Driven Design (DDD)[^2] might help, as not all values may be of equal criticality across all system components. The [Context Mapper](https://contextmapper.org/) tool, which combines DDD with value-driven analysis and design, may be useful in this context, as it allows the modeling of values at the level of a bounded context. + +### Inputs +The outputs of [Step 3](./step-3-identify-values-per-stakeholder.md), i.e. a [Value Impact Map](./../practices/value-impact-mapping.md), a value register[^1], and/or value models created with [Context Mapper](https://contextmapper.org/docs/vdad-support) constitute the input to this step. + +### Outputs +The outputs of this step are mainly adjustments to the artifacts produced in [Step 3](./step-3-identify-values-per-stakeholder.md) or even [Step 1](step-1-aquire-domain-understanding.md) and [Step 2](step-2-identify-stakeholders.md): + + * Adjusted value models with stakeholder priorities, detailed consequences and potential mitigation actions + * Adjusted [Value Impact Map (VIM)](./../practices/value-impact-mapping.md) according to defined priorities + * Adjusted value register[^1] + * Changes to domain models, user stories and/or use cases, etc., if necessary + +## Supporting Tools + +Utilize the same tools used in previous steps to make any necessary adjustments to the produced artifacts. + +## Process Navigation + + * [Complete VDAD Process](./../value-driven-analysis-and-design) + * [Previous step: Identify Values per Stakeholder](./step-3-identify-values-per-stakeholder.md) + * [Next step: Make Digitalization Decision](step-5-make-digitalization-decision.md) + +[^1]: IEEE Standard Model Process for Addressing Ethical Concerns during System Design, 2021, +[^2]: _Domain-Driven Design Reference_, Eric Evans, diff --git a/process/step-5-make-digitalization-decision.md b/process/step-5-make-digitalization-decision.md new file mode 100644 index 0000000..b4eb50a --- /dev/null +++ b/process/step-5-make-digitalization-decision.md @@ -0,0 +1,37 @@ +# VDAD Step 5: Make Digitalization Decision + +_TL;DR:_ If the negative impacts of a part of a system seem to outweigh the positive values, decide within the team (with all stakeholders) whether it should be built or not. + +## Goal and Approach +The objective of this crucial step is to make a concious decision regarding the construction of the system or feature that is planned for development. + +[Step 4: Prioritize Values](step-4-prioritize-values.md) may have revealed conflicts that cannot be resolved. It may have demonstrated that too many of the values in question are being negatively affected, and that the system in question has a harmful impact on users, other stakeholders, or society at large. + +This may seem impractical, as company leaders and business strategies may ultimately overrule such decisions anyway. However, this step allows a team or company to transparently document the pros and cons of a decision and the rationale behind it. + +The outcome of [Step 4](step-4-prioritize-values.md) should be analyzed and a decision made as to whether the project should be continued. As previously mentioned, this decision does not have to be made for the entire system. The system can be divided into bounded contexts[^1], with a digitalization decision made for each context separately. + +The decision should be documented in writing, such as in the form of an Architectural Decision Record (ADR)[^2]. This is particularly crucial in instances where the project is pursued with the understanding that significant negative consequences will be accepted. + +**Note** that we suggest to process the steps of the whole process iteratively. This step can also be postponed for a future iteration in case the team and/or stakeholders want(s) to delay the decision and gather additional insights upfront. The iterative approach also allows revisiting already made decisions later. + +### Inputs +The inputs for this step are the outputs created in the previous steps, with particular attention to the priorities and conflicts defined and unveiled in [Step 4](step-4-prioritize-values.md). + +### Outputs +The result of this step can be a simple 'Yes' or 'No'; potentially per bounded context. Some parts of the system might be build while others are not. +However, preferably one creates an ADR[^2] including the decision rationale. + +## Supporting Tools + +The [homepage of the ADR GitHub organization](https://adr.github.io/) lists several templates and tools that can be used to write ADRs, including MADR and Y-Statements, a light template for architectural decision capturing.[^3] + +## Process Navigation + + * [Complete VDAD Process](./../value-driven-analysis-and-design) + * [Previous step: Prioritize Values](step-4-prioritize-values.md) + * [Next step: Derive New and Adjust Existing Requirements](step-6-derive-new-and-adjust-existing-requirements.md) + +[^1]: _Domain-Driven Design Reference_, Eric Evans, +[^2]: +[^3]: _Y-Statements: A light template for architectural decision capturing_, Doc SoC (aka ZIO), 2020, diff --git a/process/step-6-derive-new-and-adjust-existing-requirements.md b/process/step-6-derive-new-and-adjust-existing-requirements.md new file mode 100644 index 0000000..5fb373d --- /dev/null +++ b/process/step-6-derive-new-and-adjust-existing-requirements.md @@ -0,0 +1,38 @@ +# VDAD Step 6: Derive New and Adjust Existing Requirements + +_TL;DR:_ Treat ethical values as a type or category of Non-Functional Requirements (NFRs) that complement the desired software qualities. Aim at shaping the requirements in such a way that positive values are promoted and negative values contained as much as possible. + +## Goal and Approach +Once the positive and negative consequences on the stakeholders' values have been analyzed and a digitalization decision has been made, the objective of this step is to adjust existing requirements and incorporate ethical values into functional and non-functional requirements. + +Typically, ethical values can be carved into NFRs; while defined mitigation actions from previous steps can also lead to additional functional requirements. + +In accordance with the values identified in [Step 3](step-3-identify-values-per-stakeholder.md) and their priorities defined in [Step 4](step-4-prioritize-values.md), NFRs shall be written to ensure the protection and fostering of these values throughout the system's lifecycle. NFRs should be specified in a [SMART](https://socadk.github.io/design-practice-repository/activities/DPR-SMART-NFR-Elicitation.html) way: for instance, the 'M' property makes them measurable. It must be possible to check whether the NFR is satisfied or not. + +Existing approaches towards NFRs such as the arc42 Quality Model[^2], Attribute-Driven Design (ADD)[^3] or ATAM (Method for Architecture Evaluation)[^4] could be applied. + +Furthermore, any necessary adjustments to existing requirements must be made to avoid any adverse impact on the values in question. The mitigation actions identified in previous steps must be respected in this step. + +### Inputs +All outputs of the previous steps have to be respected as input in this step. + +### Outputs +All kinds of requirements can be output to this step. + +## Supporting Tools + +The requirements can be documented in textual form with word processors, requirements management tools, and/or with special-purpose notations as the ones suggested in ESE[^1]. + +The arc42 Quality Model [^2] contains many examples as well as definitions and classifications of NFRs of all kinds. Attribute-Driven Design (ADD)[^3] or ATAM (Method for Architecture Evaluation)[^4] can be helpful approaches in this step as well. + +## Process Navigation + + * [Complete VDAD Process](./../value-driven-analysis-and-design) + * [Previous step: Make Digitalization Decision](step-5-make-digitalization-decision.md) + * [Next step: Design Software Architecture](step-7-design-software-architecture.md) + + +[^1]: +[^2]: +[^3]: +[^4]: diff --git a/process/step-7-design-software-architecture.md b/process/step-7-design-software-architecture.md new file mode 100644 index 0000000..68b4a77 --- /dev/null +++ b/process/step-7-design-software-architecture.md @@ -0,0 +1,46 @@ +# VDAD Step 7: Design Software Architecture + +_TL;DR:_ Incorporate the values of your stakeholders in all decisions about architecture, coding, and testing. Apply domain-driven practices in order to apply the ubiquitous language about the domain knowledge, stakeholders and values to your software architecture, design and code. + +## Goal and Approach +The goal of this last step is business as usual, but still worth mentioning: come up with an adequate software architecture that satisfies the functional requirements as well as ethical, and other non-functional requirements elaborated in [Step 6](step-6-derive-new-and-adjust-existing-requirements.md). + +However, in the spirit of Domain-Driven Design (DDD), the domain and value models and their ubiquitous language, context maps, etc. (artifacts produced in earlier steps) are still relevant to the design and the architecture of the software as well. + +The following, exemplary activities of the Design Practice Repository (DPR)[^1] are typically performed during this step: + + * Architectural Decision Capturing[^2] + * Architecture Modeling[^3] + * Strategic Domain-Driven Design (DDD)[^4] + * Tactic(al) DDD[^5] + +### Inputs +The input to this step are mainly the requirements elicited in [Step 6](step-6-derive-new-and-adjust-existing-requirements.md). However, as mentioned in the approach above, artifacts such as domain and value models of earlier steps can also influence design and architecture. + +### Outputs +As the name of this step indicates, this step shall produce artifacts describing the software architecture. This can be Architectural Decision Records (ADRs)[^6], component diagrams, deployment models, etc. arc42[^7] suggests a twelve-part section structure to organize this design output. + +## Supporting Tools + +It is not feasible to provide an exhaustive list of tools that can be employed to document software architecture, as the number is vast. However, a few suggestions that might be suitable: + + * arc42[^7] is available for many formats, such as docx, latex, asciidoc, markdown, etc., and can therefore be used with many editors and tools. + * Architectural Decision Records (ADRs)[^6] can be written in many formats as well. Many tools are available as well. + * [Context Mapper](https://contextmapper.org) supports several other steps of the VDAD process already and might therefore be a nice choice to generate component diagrams, context maps, etc. when applying DDD. + * [PlantUML](https://plantuml.com/) is another DSL-based tools to write UML diagrams in textual form. + +There are many online resources about software architecture topics; checkout the following collection of pointers for software architects, if you are interested: [Architectural Knowledge Hubs - Online Resources for Software Architects (Cloud Application Lab @ OST)](https://www.ost.ch/de/forschung-und-dienstleistungen/informatik/ifs-institut-fuer-software/labs/cloud-application-lab/architectural-knowledge-management-akm/architectural-knowledge-hubs) + +## Process Navigation + + * [Complete VDAD Process](./../value-driven-analysis-and-design) + * [Previous step: Derive New and Adjust Existing Requirements](step-6-derive-new-and-adjust-existing-requirements.md) + * **Whats next?** Please read the notes on *[Process Continuation](step-infinity-process-continuation.md)*. + +[^1]: +[^2]: +[^3]: +[^4]: +[^5]: +[^6]: +[^7]: diff --git a/process/step-infinity-process-continuation.md b/process/step-infinity-process-continuation.md new file mode 100644 index 0000000..16b72e6 --- /dev/null +++ b/process/step-infinity-process-continuation.md @@ -0,0 +1,24 @@ +# Process Continuation + +_TL;DR:_ Iterate over Steps 1 to 7. + +## Iterate over Steps and Process + +As indicated in the following process illustration, neither the individual steps nor the entire VDAD process should be conducted a linear, unidirectional way. + +![Value-Driven Analysis and Design (VDAD) Process](./../images/vdad-process.jpg) + +It is necessary to iterate over the individual steps and the process as a whole in order to evolve the produced artifacts in each step. Each step may yield new insights that are relevant for subsequent steps. For example, while stakeholders of different kinds learn about domain context, requirements, and system capabilities, they might want to reprioritize and/or elicit additional values. + +Steps might further have bidirectional dependencies. For instance, while understanding the domain, new stakeholders might be found. An analysis of these stakeholders might bring new insights about the domain (Steps 1 and 2). + +## Process Navigation + + * [Overview](README.md) + * [Step 1: Aquire Domain Understanding](step-1-aquire-domain-understanding.md) + * [Step 2: Identify Stakeholders](step-2-identify-stakeholders.md) + * [Step 3: Identify Values per Stakeholder](step-3-identify-values-per-stakeholder.md) + * [Step 4: Prioritize Values](step-4-prioritize-values.md) + * [Step 5: Make Digitalization Decision](step-5-make-digitalization-decision.md) + * [Step 6: Derive New and Adjust Existing Requirements](step-6-derive-new-and-adjust-existing-requirements.md) + * [Step 7: Design Software Architecture](step-7-design-software-architecture.md) diff --git a/process/template.md b/process/template.md new file mode 100644 index 0000000..b1211af --- /dev/null +++ b/process/template.md @@ -0,0 +1,22 @@ +# VDAD Step X: {step name} + +_TL;DR:_ {bold face description of step}. + +## Goal and Approach +Describe the goal of the steps and how to proceed. Recommend practices. + +### Inputs +Describe what artifacts, models, etc. can be useful as inputs to the step. + +### Outputs +Describe what artifacts, models, etc. shall be produced by this step. + +## Supporting Tools + +List tools that can support this step. + +## Process Navigation + + * [Complete VDAD Process](./../value-driven-analysis-and-design) + * Link previous step + * Link next step diff --git a/related-work.md b/related-work.md new file mode 100644 index 0000000..42da615 --- /dev/null +++ b/related-work.md @@ -0,0 +1,25 @@ +# Project Background and Related Work + +The Value-Driven Analysis and Design (VDAD) process and this repository have been crafted as part of the project «Just Enough Digitalization» at [Eastern Switzerland University of Applied Sciences (OST)](https://www.ost.ch). Please contact [Stefan Kapferer](https://www.ost.ch/de/person/stefan-kapferer-2046) to get in touch with us. + +## VDAD-Related Papers + + * _Value-Driven Analysis and Design: Applying Domain-driven Practices in Ethical Software Engineering_, Stefan Kapferer, Olaf Zimmermann and Mirko Stocker, EuroPLoP 2024, _to be published soon_ + * _Towards responsible software engineering: combining value-based processes, agile practices, and green metering_, Stefan Kapferer, Mirko Stocker and Olaf Zimmermann, IEEE International Symposium on Technology and Society (ISTAS 2024), _to be published soon_ + +## Related Approaches and Processes + + * [IEEE Standard Model Process for Addressing Ethical Concerns during System Design a.k.a. "IEEE 7000 Standard"](https://ieeexplore.ieee.org/document/9536679) + * [Value-Based Engineering (VBE)](https://www.value-based-engineering.com/) + * Offering nice introduction [videos](https://www.value-based-engineering.com/videos), such as ["What are Values"](https://youtu.be/aYqCmmkrguI) by Sarah Spiekermann + * [Ethical Software Engineering (ESE)](https://github.com/ethical-se/ese-practices) + * ESE featured in _Bringing Ethical Values into Agile Software Development_, ETHICOMP 2024, [Paper](https://raw.githubusercontent.com/ethical-se/ese-practices/main/resources/ESE-ETHICOMP2024FullPaperAuthorsCopyV101.pdf) + * Proactive CARE framework: + * Gotterbarn, D., Kirkpatrick M.S., Wolf M.J., "From the Page to Practice: Support for Computing Professionals Using a Code of Ethics", Proc. of ETHCICOMP 2022 ([Proceedings PDF](https://sites.utu.fi/ethicomp2022/wp-content/uploads/sites/1104/2022/09/Ethicomp-2022-Proceedings_Corrected.pdf)) + * Software Development Impact Statement (SoDIS) process: + * Gotterbarn, D., Rogerson, S., "Responsible Risk Assessment with Software Development: Creating the Software Development Impact Statement". Communications of the Association for Information Systems, 15, 2005 ([PDF](https://doi.org/10.17705/1CAIS.01540)) + * Consequence Scanning – an agile practice for responsible innovators: + +**_to be continued_** + + > Please refer to the following page of the ESE repository for the time being: . diff --git a/tools.md b/tools.md new file mode 100644 index 0000000..faae72a --- /dev/null +++ b/tools.md @@ -0,0 +1,7 @@ +# VDAD Tool Support + +As suggested throughout the [seven VDAD steps](./process/README.md), many general-purpose visual tools exist that can support the process, for instance, online whiteboards. + +However, there are not many that support modeling based on Domain-Driven Design (DDD)[^1] patterns (strategic and tactical DDD), as well as stakeholder and value modeling, all in one tool. Therefore, we would like to point out our open source tool [Context Mapper](https://contextmapper.org), which supports many VDAD steps with its Context Mapping Language (CML) and generators that automatically create [Stakeholder Maps](./practices/stakeholder-mapping.md) and [Value Impact Maps](./practices/value-impact-mapping.md). Check it out [here](https://contextmapper.org/docs/vdad-support). + +[^1]: _Domain-Driven Design: Tackling Complexity in the Heart of Software_, Eric Evans, 2003, https://www.amazon.de/-/en/Eric-Evans/dp/0321125215 diff --git a/user-stories.md b/user-stories.md new file mode 100644 index 0000000..2544e79 --- /dev/null +++ b/user-stories.md @@ -0,0 +1,73 @@ +# Who should use VDAD? + +_**Who and why should apply Value-Driven Analysis and Design (VDAD)?**_ + +In principle, VDAD is aimed at anyone involved in the process of software engineering or the creation of digital solutions in general. From company founders and (product) managers to requirements and software engineers we want to address everyone who wants to craft software that is valuable and does not harm humanity and our values. + +The following [user stories](https://socadk.github.io/design-practice-repository/artifact-templates/DPR-UserStory.html) serve to exemplify potential applications of VDAD and illustrate the mission of our project. + +## 1. Product Managers + +### Story 1.a) +~~~ +As a product manager of a software-intensive system, +I want to make sure that the system is not only successful in its market and pleasing and/or helping its users, +but also meets the ethical expectations of everybody involved with it. +~~~ + +### Story 1.b) +~~~ +As a responsible product manager of a software-intensive system, +I want to raise awareness for ethical concerns on all levels of my organization, + from executive managment to business domain experts to DevOps teams, +so that this important but presumably unwelcome topic area becomes a first class citizen + of software and systems engineering right next to business value and end user wants and needs. +~~~ + +## 2. DevOps Team Members + +### Story 2.a) +~~~ +As a responsible member of the development and operations team(s) for a software-intensive system, +I want to live up to my personal and my communities' values and beliefs in my daily work + despite business and management pressure that possibly causes goal conflicts +so that I do not feel bad/suffer from bad conscience. I walk the talk. +~~~ + +### Story 2.b) +~~~ +As a member of the development and operations team(s) for a software-intensive system, +I want to express and explain my ethical values with the priorities they have for me personally +so that my voice/opinion cannot be ignored easily and that I am prepared for clarification + and conflict resolution discussions with peers and people in other roles. +~~~ + +## 3. Coaches / Mentors / Value Leads +"Value lead" is a term from the IEEE 7000 standard[^1]. Checkout the standard or the role description in the ESE repository[^2] for a detailed description of this role. + +### Story 3.a) +~~~ +As a value lead, +I want to help product managers, DevOps teams, and other system stakeholders to + identify, elicit and prioritize their respective ethical values - both obvious and hidden ones, + both present and future ones, both easy-to-agree and possibly controversial ones, +so that all project members are optimally supported in developing systems that foster positive values + and reduce any negative impact of values. +~~~ + +### Story 3.b) +~~~ +As a value lead (a term from IEEE Std. 7000), +I want to help product managers, DevOps teams, and other system stakeholders to discuss + and document the positive and negative consequences of ethical values in the context of the system under construction + along with possible remedial actions +so that economic impact such as sales losses and reputation damage can be avoided + and risks of different kinds be managed and mitigated. +~~~ + +## To be continued +Note that the above collection of user stories is not exhaustive/complete. Feel free to [contribute](CONTRIBUTING.md) your ideas. + + +[^1]: IEEE Standard Model Process for Addressing Ethical Concerns during System Design, 2021, https://ieeexplore.ieee.org/document/9536679 +[^2]: _Value Lead_, ESE repository,