Skip to content

Commit

Permalink
Merge branch 'issue-7'
Browse files Browse the repository at this point in the history
  • Loading branch information
@MarkusTiede
MarkusTiede committed May 7, 2024
2 parents bcbc2bd + 0fe75c4 commit 0543fd0
Show file tree
Hide file tree
Showing 21 changed files with 1,029 additions and 0 deletions.
2 changes: 2 additions & 0 deletions .gitignore
View file
@@ -0,0 +1,2 @@
target
**/.DS_Store
126 changes: 126 additions & 0 deletions pom.xml
View file
@@ -0,0 +1,126 @@
<?xml version="1.0" encoding="UTF-8"?>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>

<groupId>ch.bfh.ipst.dsl</groupId>
<artifactId>civil42</artifactId>
<version>0.0.1-SNAPSHOT</version>

<name>civil42</name>
<url>https://github.com/digital-sustainability/civil42</url>

<properties>
<asciidoctor-maven-plugin.version>3.0.0</asciidoctor-maven-plugin.version>
<asciidoctorj.version>2.5.12</asciidoctorj.version>
<asciidoctorj-pdf.version>2.3.15</asciidoctorj-pdf.version>
<asciidoctorj-pdf.plugin.version>2.3.15</asciidoctorj-pdf.plugin.version>
<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
</properties>

<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj</artifactId>
<version>${asciidoctorj.version}</version>
</dependency>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>${asciidoctorj-pdf.version}</version>
</dependency>
</dependencies>

<build>
<plugins>
<plugin>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctor-maven-plugin</artifactId>
<version>${asciidoctor-maven-plugin.version}</version>
<dependencies>
<dependency>
<groupId>org.asciidoctor</groupId>
<artifactId>asciidoctorj-pdf</artifactId>
<version>${asciidoctorj-pdf.plugin.version}</version>
</dependency>
</dependencies>
<executions>
<execution>
<id>output-html</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>html</backend>
<attributes>
<toc/>
<linkcss>false</linkcss>
<source-highlighter>coderay</source-highlighter>
<imagesdir>images</imagesdir>
</attributes>
<outputDirectory>target/docs/html</outputDirectory>
</configuration>
</execution>
<execution>
<id>output-pdf</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
</execution>
<execution>
<id>asciidoc-to-docbook</id>
<phase>generate-resources</phase>
<goals>
<goal>process-asciidoc</goal>
</goals>
<configuration>
<backend>docbook</backend>
<doctype>book</doctype>
<attributes>
<imagesdir>images</imagesdir>
</attributes>
<outputDirectory>target/docs/docbook</outputDirectory>
</configuration>
</execution>
</executions>
<configuration>
<backend>pdf</backend>
<doctype>book</doctype>
<outputDirectory>target/docs/pdf</outputDirectory>
</configuration>
</plugin>
<plugin>
<groupId>org.codehaus.mojo</groupId>
<artifactId>exec-maven-plugin</artifactId>
<version>3.1.0</version>
<executions>
<execution>
<phase>verify</phase>
<goals>
<goal>exec</goal>
</goals>
</execution>
</executions>
<configuration>
<executable>pandoc</executable>
<!-- optional -->
<workingDirectory>target</workingDirectory>
<arguments>
<argument>-f</argument>
<argument>docbook</argument>
<argument>-s</argument>
<argument>docs/docbook/arc42.xml</argument>
<argument>-o</argument>
<argument>docs/arc42.docx</argument>
</arguments>
<environmentVariables>
<LANG>de_DE</LANG>
</environmentVariables>
</configuration>
</plugin>
</plugins>
</build>
</project>
98 changes: 98 additions & 0 deletions src/docs/asciidoc/arc42.adoc
View file
@@ -0,0 +1,98 @@
// header file for arc42-template,
// including all help texts
//
// ====================================


// configure DE settings for asciidoc
include::content/config.adoc[]

= image:arc42-logo.png[arc42] Template
:revnumber: 8.2 DE
:revdate: Januar 2023
:revremark: (basiert auf AsciiDoc Version)
// toc-title definition MUST follow document title without blank line!
:toc-title: Inhaltsverzeichnis

//additional style for arc42 help callouts
ifdef::backend-html5[]
++++
<style>
.arc42help {font-size:small; width: 14px; height: 16px; overflow: hidden; position: absolute; right: 0; padding: 2px 0 3px 2px;}
.arc42help::before {content: "?";}
.arc42help:hover {width:auto; height: auto; z-index: 100; padding: 10px;}
.arc42help:hover::before {content: "";}
@media print {
.arc42help {display:none;}
}
</style>
++++
endif::backend-html5[]


include::content/about-arc42.adoc[]

// horizontal line
***

[role="arc42help"]
****
[NOTE]
====
Diese Version des Templates enthält Hilfen und Erläuterungen.
Sie dient der Einarbeitung in arc42 sowie dem Verständnis der Konzepte.
Für die Dokumentation eigener System verwenden Sie besser die _plain_ Version.
====
****


// numbering from here on
:numbered:

<<<<
// 1. Anforderungen und Ziele
include::content/01_introduction_and_goals.adoc[]

<<<<
// 2. Randbedingungen
include::content/02_architecture_constraints.adoc[]

<<<<
// 3. Kontextabgrenzung
include::content/03_system_scope_and_context.adoc[]

<<<<
// 4. Lösungsstrategie
include::content/04_solution_strategy.adoc[]

<<<<
// 5. Bausteinsicht
include::content/05_building_block_view.adoc[]

<<<<
// 6. Laufzeitsicht
include::content/06_runtime_view.adoc[]

<<<<
// 7. Verteilungssicht
include::content/07_deployment_view.adoc[]

<<<<
// 8. Querschnittliche Konzepte
include::content/08_concepts.adoc[]

<<<<
// 9. Entscheidungen
include::content/09_architecture_decisions.adoc[]

<<<<
// 10. Qualitätsanforderungen
include::content/10_quality_requirements.adoc[]

<<<<
// 11. Risiken
include::content/11_technical_risks.adoc[]

<<<<
// 12. Glossar
include::content/12_glossary.adoc[]
89 changes: 89 additions & 0 deletions src/docs/asciidoc/content/01_introduction_and_goals.adoc
View file
@@ -0,0 +1,89 @@
ifndef::imagesdir[:imagesdir: ../images]

[[section-introduction-and-goals]]
== Einführung und Ziele

[role="arc42help"]
****
Beschreibt die wesentlichen Anforderungen und treibenden Kräfte, die bei der Umsetzung der Softwarearchitektur und Entwicklung des Systems berücksichtigt werden müssen.
Dazu gehören:
* zugrunde liegende Geschäftsziele,
* wesentliche Aufgabenstellungen,
* wesentliche funktionale Anforderungen,
* Qualitätsziele für die Architektur und
* relevante Stakeholder und deren Erwartungshaltung.
****

=== Aufgabenstellung

[role="arc42help"]
****
.Inhalt
Kurzbeschreibung der fachlichen Aufgabenstellung, treibenden Kräfte, Extrakt (oder Abstract) der Anforderungen.
Verweis auf (hoffentlich vorliegende) Anforderungsdokumente (mit Versionsbezeichnungen und Ablageorten).
.Motivation
Aus Sicht der späteren Nutzung ist die Unterstützung einer fachlichen Aufgabe oder Verbesserung der Qualität der eigentliche Beweggrund, ein neues System zu schaffen oder ein bestehendes zu modifizieren.
.Form
Kurze textuelle Beschreibung, eventuell in tabellarischer Use-Case Form.
Sofern vorhanden, sollte die Aufgabenstellung Verweise auf die entsprechenden Anforderungsdokumente enthalten.
Halten Sie diese Auszüge so knapp wie möglich und wägen Sie Lesbarkeit und Redundanzfreiheit gegeneinander ab.
.Weiterführende Informationen
Siehe https://docs.arc42.org/section-1/[Anforderungen und Ziele] in der online-Dokumentation (auf Englisch!).
****

=== Qualitätsziele

[role="arc42help"]
****
.Inhalt
Die Top-3 bis Top-5 der Qualitätsanforderungen für die Architektur, deren Erfüllung oder Einhaltung den maßgeblichen Stakeholdern besonders wichtig sind.
Gemeint sind hier wirklich Qualitätsziele, die nicht unbedingt mit den Zielen des Projekts übereinstimmen.
Beachten Sie den Unterschied.
Hier ein Überblick möglicher Themen (basierend auf dem ISO 25010 Standard):
image::01_2_iso-25010-topics-DE.drawio.png["Kategorien von Qualitätsanforderungen"]
.Motivation
Weil Qualitätsziele grundlegende Architekturentscheidungen oft maßgeblich beeinflussen, sollten Sie die für Ihre Stakeholder relevanten Qualitätsziele kennen, möglichst konkret und operationalisierbar.
.Form
Tabellarische Darstellung der Qualitätsziele mit möglichst konkreten Szenarien, geordnet nach Prioritäten.
****

=== Stakeholder

[role="arc42help"]
****
.Inhalt
Expliziter Überblick über die Stakeholder des Systems – über alle Personen, Rollen oder Organisationen –, die
* die Architektur kennen sollten oder
* von der Architektur überzeugt werden müssen,
* mit der Architektur oder dem Code arbeiten (z.B. Schnittstellen nutzen),
* die Dokumentation der Architektur für ihre eigene Arbeit benötigen,
* Entscheidungen über das System und dessen Entwicklung treffen.
.Motivation
Sie sollten die Projektbeteiligten und -betroffenen kennen, sonst erleben Sie später im Entwicklungsprozess Überraschungen.
Diese Stakeholder bestimmen unter anderem Umfang und Detaillierungsgrad der von Ihnen zu leistenden Arbeit und Ergebnisse.
.Form
Tabelle mit Rollen- oder Personennamen, sowie deren Erwartungshaltung bezüglich der Architektur und deren Dokumentation.
****

[cols="1,1,2" options="header"]
|===
|Rolle |Kontakt |Erwartungshaltung
| _<Rolle-1>_ | _<Kontakt-1>_ | _<Erwartung-1>_
| _<Rolle-2>_ | _<Kontakt-2>_ | _<Erwartung-2>_
|===
25 changes: 25 additions & 0 deletions src/docs/asciidoc/content/02_architecture_constraints.adoc
View file
@@ -0,0 +1,25 @@
ifndef::imagesdir[:imagesdir: ../images]

[[section-architecture-constraints]]
== Randbedingungen

[role="arc42help"]
****
.Inhalt
Randbedingungen und Vorgaben, die ihre Freiheiten bezüglich Entwurf, Implementierung oder Ihres Entwicklungsprozesses einschränken.
Diese Randbedingungen gelten manchmal organisations- oder firmenweit über die Grenzen einzelner Systeme hinweg.
.Motivation
Für eine tragfähige Architektur sollten Sie genau wissen, wo Ihre Freiheitsgrade bezüglich der Entwurfsentscheidungen liegen und wo Sie Randbedingungen beachten müssen.
Sie können Randbedingungen vielleicht noch verhandeln, zunächst sind sie aber da.
.Form
Einfache Tabellen der Randbedingungen mit Erläuterungen.
Bei Bedarf unterscheiden Sie technische, organisatorische und politische Randbedingungen oder übergreifende Konventionen (beispielsweise Programmier- oder Versionierungsrichtlinien, Dokumentations- oder Namenskonvention).
.Weiterführende Informationen
Siehe https://docs.arc42.org/section-2/[Randbedingungen] in der online-Dokumentation (auf Englisch!).
****

0 comments on commit 0543fd0

Please sign in to comment.