|
28 | 28 | "description": "How we document architecture with diagrams, ADRs, and decision evaluation", |
29 | 29 | "descriptionDe": "Wie wir Architektur mit Diagrammen, ADRs und Entscheidungsbewertung dokumentieren", |
30 | 30 | "anchors": ["arc42", "c4-diagrams", "adr-according-to-nygard", "pugh-matrix"], |
31 | | - "template": "Architecture documentation follows arc42 with all 12 sections.\n\nDiagrams are required per section:\n- §3.1 Business context: business-process / value-flow diagram\n- §3.2 Technical context: classical context diagram (PlantUML/Mermaid)\n- §5 Building blocks: C4 Level 1 (System Context), Level 2 (Container), and Level 3 (Component) where decomposition adds clarity\n- §6 Runtime view: sequence or activity diagram per named scenario\n\nDecisions:\n- Every architecture decision documented as an ADR according to Nygard (Context, Decision, Status, Consequences).\n- Each ADR includes a Pugh Matrix with 3-point scale (-1, 0, +1) evaluating alternatives against quality goals.\n- When the rationale cannot be confirmed by a stakeholder, ADR Status is \"Accepted (inferred)\" and Pugh cells requiring team judgment are marked `?` rather than filled with assumptions.\n\nCrosscutting concepts (§8) are listed in the separate \"Crosscutting Concepts\" contract.", |
32 | | - "templateDe": "Architekturdokumentation folgt arc42 mit allen 12 Abschnitten.\n\nDiagramme sind pro Abschnitt verpflichtend:\n- §3.1 Fachlicher Kontext: Geschäftsprozess- / Wertfluss-Diagramm\n- §3.2 Technischer Kontext: klassisches Kontextdiagramm (PlantUML/Mermaid)\n- §5 Bausteinsicht: C4 Level 1 (System Context), Level 2 (Container) und Level 3 (Component), wo Zerlegung Klarheit bringt\n- §6 Laufzeitsicht: Sequenz- oder Aktivitätsdiagramm pro benanntem Szenario\n\nEntscheidungen:\n- Jede Architekturentscheidung als ADR nach Nygard dokumentiert (Kontext, Entscheidung, Status, Konsequenzen).\n- Jedes ADR enthält eine Pugh-Matrix mit 3-Punkt-Skala (-1, 0, +1) zur Bewertung von Alternativen gegen Qualitätsziele.\n- Wenn die Begründung nicht von einem Stakeholder bestätigt werden kann, lautet der ADR-Status \"Accepted (inferred)\", und Pugh-Zellen, die Team-Urteil erfordern, werden mit `?` markiert statt mit Annahmen gefüllt.\n\nQuerschnittliche Konzepte (§8) sind im separaten Contract \"Crosscutting Concepts\" beschrieben.", |
| 31 | + "template": "Architecture documentation follows arc42 with all 12 sections.\n\nSections are numbered as in arc42 itself: `1.`, `1.1`, `2.`, … No `§` prefix in the output (the `§` symbol is used in this contract only to reference arc42 sections, not as the prescribed notation).\n\nFile formats:\n- arc42, ADRs, PRD, specification documents: AsciiDoc (.adoc), per the Docs-as-Code contract.\n- Use-case files and entity model retain whatever format the AIUP-reverse-engineer skill produces (Markdown today).\n- Question Tree and Open Questions: AsciiDoc (.adoc).\n\nDiagrams are required per section, all as PlantUML:\n- 3.1 Business context: business-process / value-flow diagram (BPMN or annotated sequence).\n- 3.2 Technical context: classical context diagram showing the system as a black box with all external systems and protocols labelled.\n- 5.1 / 5.2 / 5.3 Building blocks: C4 model using the C4-PlantUML standard library (`!include` C4_Context / C4_Container / C4_Component) with the proper stereotypes (`Person`, `System`, `Container`, `Component`, `Rel`). Generic `box`/`rectangle` shapes do not satisfy this requirement.\n- 6 Runtime view: PlantUML sequence diagram per named scenario.\n\nDecisions:\n- Every architecture decision documented as an ADR according to Nygard (Context, Decision, Status, Consequences).\n- Each ADR includes a Pugh Matrix with 3-point scale (-1, 0, +1) evaluating alternatives against quality goals.\n- When the rationale cannot be confirmed by a stakeholder, ADR Status is \"Accepted (inferred)\" and Pugh cells requiring team judgment are marked `?` rather than filled with assumptions.\n\nCrosscutting concepts (§8) are listed in the separate \"Crosscutting Concepts\" contract.", |
| 32 | + "templateDe": "Architekturdokumentation folgt arc42 mit allen 12 Abschnitten.\n\nAbschnitte werden wie in arc42 selbst nummeriert: `1.`, `1.1`, `2.`, … Kein `§`-Präfix in der Ausgabe (das `§`-Zeichen wird in diesem Contract nur zur Referenzierung von arc42-Abschnitten verwendet, nicht als vorgeschriebene Notation).\n\nDateiformate:\n- arc42, ADRs, PRD, Spezifikationsdokumente: AsciiDoc (.adoc), gemäß Docs-as-Code-Contract.\n- Use-Case-Dateien und Entity Model behalten das Format, das die AIUP-reverse-engineer-Skill erzeugt (heute Markdown).\n- Question Tree und Open Questions: AsciiDoc (.adoc).\n\nDiagramme sind pro Abschnitt verpflichtend, alle als PlantUML:\n- 3.1 Fachlicher Kontext: Geschäftsprozess- / Wertfluss-Diagramm (BPMN oder annotierte Sequenz).\n- 3.2 Technischer Kontext: klassisches Kontextdiagramm, das das System als Black Box zeigt, mit allen externen Systemen und beschrifteten Protokollen.\n- 5.1 / 5.2 / 5.3 Bausteinsicht: C4-Modell mit der C4-PlantUML-Standardbibliothek (`!include` C4_Context / C4_Container / C4_Component) und den korrekten Stereotypen (`Person`, `System`, `Container`, `Component`, `Rel`). Generische `box`/`rectangle`-Formen erfüllen diese Anforderung nicht.\n- 6 Laufzeitsicht: PlantUML-Sequenzdiagramm pro benanntem Szenario.\n\nEntscheidungen:\n- Jede Architekturentscheidung als ADR nach Nygard dokumentiert (Kontext, Entscheidung, Status, Konsequenzen).\n- Jedes ADR enthält eine Pugh-Matrix mit 3-Punkt-Skala (-1, 0, +1) zur Bewertung von Alternativen gegen Qualitätsziele.\n- Wenn die Begründung nicht von einem Stakeholder bestätigt werden kann, lautet der ADR-Status \"Accepted (inferred)\", und Pugh-Zellen, die Team-Urteil erfordern, werden mit `?` markiert statt mit Annahmen gefüllt.\n\nQuerschnittliche Konzepte (§8) sind im separaten Contract \"Crosscutting Concepts\" beschrieben.", |
33 | 33 | "category": "architecture" |
34 | 34 | }, |
35 | 35 | { |
|
116 | 116 | "description": "How we write and build documentation", |
117 | 117 | "descriptionDe": "Wie wir Dokumentation schreiben und bauen", |
118 | 118 | "anchors": ["docs-as-code", "plain-english-strunk-white", "gutes-deutsch-wolf-schneider"], |
119 | | - "template": "Documentation follows Docs-as-Code according to Ralf D. Müller:\n- AsciiDoc as format, PlantUML for inline diagrams, built by docToolchain\n- Version-controlled, peer-reviewed, and built automatically\n- Plain English according to Strunk & White (or Gutes Deutsch nach Wolf Schneider)", |
120 | | - "templateDe": "Dokumentation folgt Docs-as-Code nach Ralf D. Müller:\n- AsciiDoc als Format, PlantUML für Inline-Diagramme, gebaut von docToolchain\n- Versioniert, reviewt und automatisch gebaut\n- Gutes Deutsch nach Wolf Schneider (oder Plain English nach Strunk & White)", |
| 119 | + "template": "Documentation follows Docs-as-Code according to Ralf D. Müller:\n- AsciiDoc as format, PlantUML for inline diagrams, built by docToolchain\n- Version-controlled, peer-reviewed, and built automatically\n- Plain English according to Strunk & White (or Gutes Deutsch nach Wolf Schneider)\n- Projects following this contract include the `dtcw` wrapper and `docToolchainConfig.groovy` so PlantUML / AsciiDoc actually render.", |
| 120 | + "templateDe": "Dokumentation folgt Docs-as-Code nach Ralf D. Müller:\n- AsciiDoc als Format, PlantUML für Inline-Diagramme, gebaut von docToolchain\n- Versioniert, reviewt und automatisch gebaut\n- Gutes Deutsch nach Wolf Schneider (oder Plain English nach Strunk & White)\n- Projekte, die diesem Contract folgen, enthalten den `dtcw`-Wrapper und `docToolchainConfig.groovy`, damit PlantUML / AsciiDoc tatsächlich gerendert werden.", |
121 | 121 | "category": "documentation" |
122 | 122 | }, |
123 | 123 | { |
|
0 commit comments