Merge pull request #672 from isaqb-org/consistent-citation-keys

Add and Implement ADR012 for Citation Key Standardization

Author: gernotstarke

README.adoc

@@ -455,6 +455,16 @@ To unify upper/lowercase within the (EN) version, we use the _Chicago manual of
 
 For the German (DE) version, we don't use punctuation at the end of bullet-list items, unless on ends-of-sentences.
 
+==== Citation Keys
+
+We follow standardized citation keys:
+
+* Single author: `[lastname YYYY]`, e.g. `[Starke 2024]`
+* Multiple authors: `[lastname+ YYYY]`, e.g. `[Bass+ 2021]`
+* Standards: `[standard-id]`, e.g. `[ISO 25010:2023]`
+* Known terms/products: `[abbreviation]`, e.g. `[arc42]`
+
+See ADR-012 for complete guidelines and special cases.
 
 [[handling-references]]
 === Based on Established Content And References

docs/09-references/00-references.adoc

@@ -11,7 +11,7 @@
 
 - [[[aosa, AOSA]]] The Architecture of Open Source Applications. Edited by Amy Brown and Greg Wilson. Online: <https://aosabook.org/en/>.
 - [[[arc42, arc42]]] arc42, the open-source template for software architecture communication, online: <https://arc42.org>. Maintained on <https://github.com/arc42>
-- [[[archimate, Archimate]]] The ArchiMate® Enterprise Architecture Modeling Language, online: <https://www.opengroup.org/archimate-forum/archimate-overview>
+- [[[archimate, ArchiMate]]] The ArchiMate® Enterprise Architecture Modeling Language, online: <https://www.opengroup.org/archimate-forum/archimate-overview>
 
 // B
 - [[[bass,Bass+ 2021]]] Len Bass, Paul Clements, Rick Kazman: Software Architecture in Practice. 4^th^ Edition, Addison Wesley 2021.
@@ -24,37 +24,37 @@
 // C
 - [[[clementseval,Clements+ 2002]]] Paul Clements, Rick Kazman, Mark Klein: Evaluating Software Architectures. Methods and Case Studies. Addison Wesley, 2002.
 - [[[clementsdoc,Clements+ 2010]]] Paul Clements,  Felix Bachmann, Len Bass, David Garlan, David, James Ivers, Reed Little, Paulo Merson and Robert Nord: _Documenting Software Architectures: Views and Beyond_, 2nd edition, Addison Wesley, 2010
-- [[[cncf, Cloud-Native]]] The Cloud Native Computing Foundation, online: https://www.cncf.io/
+- [[[cncf, CloudNative]]] The Cloud Native Computing Foundation, online: https://www.cncf.io/
 
 // E
-- [[[eilebrecht,Eilebrecht+2024]]] Karl Eilebrecht, Gernot Starke: Patterns kompakt: Entwurfsmuster für effektive Software-Entwicklung (in German). 6th Edition Springer Verlag 2024.
+- [[[eilebrecht,Eilebrecht +2024]]] Karl Eilebrecht, Gernot Starke: Patterns kompakt: Entwurfsmuster für effektive Software-Entwicklung (in German). 6th Edition Springer Verlag 2024.
 
-- [[[erd, Chen 1976]]]  Chen, Peter (March 1976): _The Entity-Relationship Model - Toward a Unified View of Data_. ACM Transactions on Database Systems. 1 (1): 9–36..
+- [[[erd,Chen 1976]]]  Chen, Peter (March 1976): _The Entity-Relationship Model - Toward a Unified View of Data_. ACM Transactions on Database Systems. 1 (1): 9–36..
 - [[[evans,Evans 2004]]] Eric Evans: _Domain-Driven Design: Tackling Complexity in the Heart of Software,_ Addison-Wesley, 2004.
 
 // F
-- [[[felleisenetal, Felleisen+2014]]] Matthias Felleisen, Robert Bruce Findler, Matthew Flatt, Shriram Krishnamurthi: How to Design Programs.  Second Edition.  MIT Press, 2014. <https://htdp.org/>
+- [[[felleisenetal, Felleisen +2014]]] Matthias Felleisen, Robert Bruce Findler, Matthew Flatt, Shriram Krishnamurthi: How to Design Programs.  Second Edition.  MIT Press, 2014. <https://htdp.org/>
 
 - [[[ford,Ford 2017]]] Neil Ford, Rebecca Parsons, Patrick Kua: Building Evolutionary Architectures: Support Constant Change. OReilly 2017.
 
-- [[[fordhardparts,Ford+2021]]] Neal Ford, Mark Richards, Pramod Sadalage und Zhamak Dehghani: Software Architecture: The Hard Parts. Modern Trade-Off Analyses for Distributed Architectures. OReilly 2021.
+- [[[fordhardparts,Ford+ 2021]]] Neal Ford, Mark Richards, Pramod Sadalage und Zhamak Dehghani: Software Architecture: The Hard Parts. Modern Trade-Off Analyses for Distributed Architectures. OReilly 2021.
 - [[[fowler,Fowler 2002]]] Martin Fowler: Patterns of Enterprise Application Architecture. (PoEAA) Addison-Wesley, 2002.
 
 // G
 
-- [[[ghandietal,Ghandi+24]]] Raju Gandhi, Mark Richards and Neal Ford. Head-First Software Architecture. OReilly 2024.
-- [[[gof,Gamma+94]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.
+- [[[ghandietal,Ghandi+ 2024]]] Raju Gandhi, Mark Richards and Neal Ford. Head-First Software Architecture. OReilly 2024.
+- [[[gof,Gamma+ 1994]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides. Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.
 - [[[geewax,Geewax 2021]]] J. Geewax. API Design Patterns. Manning, 2021. This book lays out a set of design principles for building internal and public-facing APIs. 
 - [[[geirhos,Geirhos 2015]]] Matthias Geirhos. Entwurfsmuster: Das umfassende Handbuch (in German). Rheinwerk Computing Verlag. 2015
-- [[[gharbietal,Gharbi+2024]]] Mahbouba Gharbi, Arne Koschel, Andreas Rausch, Gernot Starke: Basiswissen Softwarearchitektur. 5. Auflage, dpunkt Verlag, Heidelberg 2024.
+- [[[gharbietal,Gharbi+ 2024]]] Mahbouba Gharbi, Arne Koschel, Andreas Rausch, Gernot Starke: Basiswissen Softwarearchitektur. 5. Auflage, dpunkt Verlag, Heidelberg 2024.
 - [[[Goll,Goll 2014]]] Joachim Goll: Architektur- und Entwurfsmuster der Softwaretechnik: Mit lauffähigen Beispielen in Java (in German). Springer-Vieweg Verlag, 2. Auflage 2014.
 
 // H
-- [[[hofmeister,Hofmeister et. al 1999]]] Christine Hofmeister, Robert Nord, Dilip Soni: _Applied Software Architecture_, Addison-Wesley, 1999
-- [[[hohpe,Hohpe+2004]]] Hohpe, G. and WOOLF, B.A.: _Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions_, Addison-Wesley Professional, 2004
+- [[[hofmeister,Hofmeister+ 1999]]] Christine Hofmeister, Robert Nord, Dilip Soni: _Applied Software Architecture_, Addison-Wesley, 1999
+- [[[hohpe,Hohpe+ 2004]]] Hohpe, G. and WOOLF, B.A.: _Enterprise Integration Patterns: Designing, Building, and Deploying Messaging Solutions_, Addison-Wesley Professional, 2004
 - [[[hombergs,Hombergs 2024]]] Hombergs, Tom: Get Your Hands Dirty on Clean Architecture, Packt, 2nd edition 2024.
-- [[[humble,Humble et. al 2010]]] Jez Humble, David Farley. Continuous Delivery: Reliable Software Releases through Build, Test, and Deployment Automation. Pearson International, 2010
-- [[[hruschkaetalarc42, Hruschka+2021]]] Peter Hruschka, IvanKostov and Wolfgang Reimesch: arc42-by-Example Vol 2: Architecture Documentation for Embedded Systems and IoT. Leanpub, 2021. https://leanpub.com/arc42byexample-volume2
+- [[[humble,Humble+ 2010]]] Jez Humble, David Farley. Continuous Delivery: Reliable Software Releases through Build, Test, and Deployment Automation. Pearson International, 2010
+- [[[hruschkaetalarc42, Hruschka+ 2021]]] Peter Hruschka, Ivan Kostov and Wolfgang Reimesch: arc42-by-Example Vol 2: Architecture Documentation for Embedded Systems and IoT. Leanpub, 2021. https://leanpub.com/arc42byexample-volume2
 // I
 - [[[ietf-http,IETF HTTP]]] Internet Engineering Task Force: RFC 9110, HTTP Semantics. Online: https://www.rfc-editor.org/rfc/rfc9110.html
 - [[[isaqbdownloads,iSAQB Downloads]]] iSAQB public download site.  https://public.isaqb.org. Contains curricula and mock-examination.
@@ -73,15 +73,15 @@
 // L
 - [[[lange21,Lange 2021]]] Kenneth Lange: The Functional Core, Imperative Shell Pattern, online: <https://www.kennethlange.com/functional-core-imperative-shell/>
 - [[[lehman,Lehman 1980]]] Meir M. Lehman: Programs, Life Cycles, and Laws of Software Evolution. Proceedings of the IEEE, 68(9), 1060-1076, 1980.
-- [[[lehmanwiki,Lehman's Laws]]] Laws of Software Evolution. <https://en.wikipedia.org/wiki/Lehman%27s_laws_of_software_evolution>
+- [[[lehmanwiki,Wiki-LehmansLaws]]] Laws of Software Evolution. <https://en.wikipedia.org/wiki/Lehman%27s_laws_of_software_evolution>
 - [[[lilienthal,Lilienthal 2024]]] Carola Lilienthal: Langlebige Softwarearchitekuren. 4. Auflage, dpunkt Verlag 2024.
 - [[[lilienthal-en,Lilienthal 2019]]] Carola Lilienthal: Sustainable Software Architecture: Analyze and Reduce Technical Debt. dpunkt Verlag 2019.
 - [[[liskov,Liskov 1994]]] Barbara H. Liskov, Jeannette M. Wing: A behavioral notion of subtyping. ACM Transactions on Programming Languages and Systems, Volume 16, Issue 6, 1994. <doi:10.1145/197320.197383>
 
 
 // M
 - [[[maguire, Maguire 2019]]] Sandy Maguire: Algebra-Driven Design - Elegant Solutions from Simple Building Blocks.  Leanpub, 2019.
-- [[[miller-distributed,Miller et. al]]] Heather Miller, Nat Dempkowski, James Larisch, Christopher Meiklejohn:  Distributed Programming (to appear, but content-complete) <https://github.com/heathermiller/dist-prog-book>.
+- [[[miller-distributed,Miller+]]] Heather Miller, Nat Dempkowski, James Larisch, Christopher Meiklejohn:  Distributed Programming (to appear, but content-complete) <https://github.com/heathermiller/dist-prog-book>.
 
 // N
 - [[[newman,Newman 2021]]] Sam Newman. Building Microservices - Designing Fine-Grained Systems. O'Reilly 2nd edition 2021.
@@ -97,24 +97,23 @@
 - [[[q42,Q42]]] arc42 Quality Model, online: <https://quality.arc42.org>.
 
 // R
-- [[[rajlich,Rajlich+2000]]] Václav T. Rajlich, Keith H. Bennett: A Staged Model for the Software Life Cycle. IEEE Computer 33(7): 66-71, 2000.
+- [[[rajlich,Rajlich+ 2000]]] Václav T. Rajlich, Keith H. Bennett: A Staged Model for the Software Life Cycle. IEEE Computer 33(7): 66-71, 2000.
 - [[[readcommunication,Read 2023]]] Jacqui Read: Communication Patterns - An Engineering Approach. A Guide for Developers and Architects. OReilly 2023.
-- [[[richardsfundamentals,Richards+20]]] Mark Richards, Neal Ford: Fundamentals of Software Architecture - An Engineering Approach. OReilly 2020.
-- [[[rozanskiwoods, Rozanski+11]]] Nick Rozanski, Eoin Woods: Software Systems Architecture - Working With Stakeholders Using Viewpoints and Perspectives. Addison-Wesley, 2nd edition 2011.
+- [[[richardsfundamentals,Richards+ 2020]]] Mark Richards, Neal Ford: Fundamentals of Software Architecture - An Engineering Approach. OReilly 2020.
+- [[[rozanskiwoods, Rozanski+ 2011]]] Nick Rozanski, Eoin Woods: Software Systems Architecture - Working With Stakeholders Using Viewpoints and Perspectives. Addison-Wesley, 2nd edition 2011.
 
 // S
 - [[[solid, SOLID]]] Samuel Oloruntoba and Anish Singh Walia: SOLID: The First 5 Principles of Object Oriented Design, <https://www.digitalocean.com/community/conceptual-articles/s-o-l-i-d-the-first-five-principles-of-object-oriented-design>.
-- [[[sperberklaeren, Sperber+Klaeren]]] Michael Sperber, Herber  Klaeren: Schreibe Dein Programm!  Tübingen University Press, 2023.  <https://www.deinprogramm.de/sdp/>.
+- [[[sperberklaeren, Sperber+ 2023]]] Michael Sperber, Herber  Klaeren: Schreibe Dein Programm!  Tübingen University Press, 2023.  <https://www.deinprogramm.de/sdp/>.
 - [[[starke,Starke 2024]]] Gernot Starke: Effektive Softwarearchitekturen - Ein praktischer Leitfaden (in German). 10. Auflage, Carl Hanser Verlag 2024. Website: https://esabuch.de
-- [[[starkelorz, Starke-Lorz-2023]]] Gernot Starke, Alexander Lorz: Software Architecture Foundation, CPSA Foundation® Exam Preparation. Van Haaren Publishing, 2nd edition, 2023.
-- [[[starkeetalarc42, Starke+2023]]] Gernot Starke, Michael Simons, Stefan Zörner, Ralf D. Müller, and Hendrik Lösch: arc42-by-Example - Software Architecture Documentation in Practice. Leanpub, 3rd edition 2023. https://leanpub.com/arc42byexample
+- [[[starkelorz, Starke+ 2023a]]] Gernot Starke, Alexander Lorz: Software Architecture Foundation, CPSA Foundation® Exam Preparation. Van Haaren Publishing, 2nd edition, 2023.
+- [[[starkeetalarc42, Starke+ 2023b]]] Gernot Starke, Michael Simons, Stefan Zörner, Ralf D. Müller, and Hendrik Lösch: arc42-by-Example - Software Architecture Documentation in Practice. Leanpub, 3rd edition 2023. https://leanpub.com/arc42byexample
 - [[[sysml,SysML]]] What is SysML <https://sysml.org/>. For diagrams, see also <https://sysml.org/tutorials/sysml-diagram-tutorial/>.
 
 
 
-
 // T
-- [[[distributedsystems,vanSteen+Tanenbaum]]] Andrew Tanenbaum, Maarten van Steen: Distributed Systems, Principles and Paradigms. <https://www.distributed-systems.net/>.
+- [[[distributedsystems,Tanenbaum+]]] Andrew Tanenbaum, Maarten van Steen: Distributed Systems, Principles and Paradigms. <https://www.distributed-systems.net/>.
 
 // U
 - [[[uml,UML]]] The UML reading room, collection of UML resources <https://www.omg.org/technology/readingroom/UML.htm>. See also <https://www.uml-diagrams.org/>.
@@ -124,5 +123,5 @@
 - [[[yorgey,Yorgey 2012]]] Brent A. Yorgey, Monoids: Theme and Variations. Proceedings of the 2012 Haskell Symposium, September 2012 <https://doi.org/10.1145/2364506.2364520>
 
 // Z
-- [[[zimmermann-api,Zimmermann+2022]]] Olaf Zimmermann, Mirko Stocker, Daniel Lübke, Uwe Zdun, Cesare Pautasso: Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges. Addison-Wesley, 2022.
+- [[[zimmermann-api,Zimmermann+ 2022]]] Olaf Zimmermann, Mirko Stocker, Daniel Lübke, Uwe Zdun, Cesare Pautasso: Patterns for API Design: Simplifying Integration with Loosely Coupled Message Exchanges. Addison-Wesley, 2022.
 - [[[zoerner,Zörner 2021]]] Stefan Zörner: Softwarearchitekturen dokumentieren und kommunizieren. 3. Auflage, Carl Hanser Verlag, 2021.

documentation/decisions/012-citation_key_standardization.md

@@ -0,0 +1,90 @@
+# 012 - Citation Key Standardization
+
+## Status: Accepted
+
+## Context
+
+The iSAQB curricula and related documents currently (11/2024) use inconsistent citation keys/labels for referencing sources. This includes varying formats for:
+- Multiple author references
+- Year formatting
+- Special character handling
+- Edge cases like standards, wikis, or online resources
+
+```
+[Miller et. al]
+[Sperber+Klaeren]
+[Rajlich+2000]
+[Bass+ 2021] 
+[Richards+20]
+```
+
+The use of mixed styles and formats, makes maintenance difficult and potentially confuses readers. This affects readability and synchronization between different iSAQB documents, particularly when cross-referencing between curricula, glossary, and other materials.
+
+## Decision
+
+Standardize citation keys starting with the FL curriculum, try to implement the following set of guidelines across other iSAQB documentation.
+
+### 1. Basic Format
+
+```
+[lastname YYYY]     - single author: [Starke 2024]
+[lastname+ YYYY]    - multiple authors: [Bass+ 2021]
+[lastname YYYYa]    - multiple works same year: [Buschmann 1996a]
+```
+
+Where:
+- Author is the surname of the first author only
+- YYYY is the four-digit year
+- Space between Author and Year
+- "+" indicates multiple authors
+- No space between Author and +
+
+### 2. Special Cases
+
+```
+[standard-id]       - standards: [ISO-25010:2023]
+[abbreviation]      - known terms: [arc42]
+[concept]           - concept/website without author: [SOLID], [UML]
+[Wiki-topic]        - Wikipedia: [Wiki-SOLID], [Wiki-LehmansLaws]
+[organization]      - organizations [CNCF], [CNCF 2024] 
+[lastname-concept]  - concept/website with author: [Fowler-PoEAA]
+[org-topic]         - organization docs: [IETF-HTTP], [CNCF-Cloud]
+[org-doctype]       - organization publications: [iSAQB-Glossary], [iSAQB-Foundation]
+```
+
+### 3. Naming Rules
+1. Author Names:
+   - Use surname only: "Martin Fowler" → [Fowler 2002]
+   - For multiple authors, use first author: "Gamma, Helm, Johnson, Vlissides" → [Gamma+ 1994]
+   - Alternative known names allowed: "Gang of Four" → [GoF 1994]
+   - For multiple works by same author/year, append lowercase letters (a, b, c...)
+
+2. Special Characters:
+   - Remove apostrophes: "Conway's Law" → [ConwaysLaw]
+   - Keep possessive 's': "Lehman's Laws" → [LehmansLaws]
+   - Use CamelCase for compound names: "Model View Controller" → [ModelViewController]
+   - Only if CamelCase is not applicable or confusing, use space: [IETF HTML]
+   - Keep established names/abbreviations: [arc42]
+
+3. Edge Cases:
+   - Unknown author: Use organization or short title
+   - No date available: Omit year component
+   - Standards: Keep standard number/identifier but shorten if possible: "ISO/IEC 42010:2022" → [ISO 42010:2022]
+   - Wikipedia articles: Always prefix with "Wiki-"
+   - For multiple works by same author without year, use descriptive suffix: [Fowler-Patterns], [Fowler-Testing]
+
+
+## Rationale
+
+This format:
+- Aligns with majority of existing citations in FL curriculum and glossary
+- Provides clear distinction between single/multiple authors
+- Maintains readability while being concise
+- Allows easy processing and maintenance
+- Accommodates special cases without complexity
+
+## Consequences
+
+- Apply to new citations immediately
+- Update existing citations gradually during regular document maintenance
+- Document exceptions when required