Skip to Content

Wiki source code of Dokumentation

Version 3.1 by Marco Grawunder on 2026/08/25 15:16
Hide last authors
Marco Grawunder 3.1 1 = Anforderungsanalyse =
Marco Grawunder 1.1 2
3 * Was soll umgesetzt werden? Wie sieht diese Welt aus?
4 ** Wer sind die Akteure?
5 ** Welche User-Stories gibt es?
6 ** Welche nicht funktionalen Anforderungen gibt es?
7 ** Welche Objekte gibt es: Objektmodell (als Klassendiagramm)
8 ** Wie interagieren die miteinander (wichtig!): Dynamisches Modell (tyischerweise als Sequenz-, Aktivitäts- oder Zustandsdiagramm)
9 *** Sequenzdiagramm: Wenn man sehr genau weiß, wie die Abläufe sind
10 *** Aktivitätsdiagramm und Zustandsdiagramm: Kann erstmal auf einer abstrakten Ebene passieren und später verfeinert werden
11 * Dokumentation schrittweise (!) anpassen/erweitern
12 * Abgabe:
Marco Grawunder 2.1 13 ** [[Zwischenpräsentation>>doc:Main.Präsentationen.WebHome]] (siehe dort)
Marco Grawunder 1.1 14 ** zum Ende des Projektes finale Version
15 ** Dokumentation in einem extra Dokument (nicht auf GitLab verweisen).
Marco Grawunder 2.1 16 * Beachten: [[Anforderungen Dokumentation>>doc:Main.Dokumentation.WebHome||anchor="HAnforderungen:Dokumentation"]]
Marco Grawunder 1.1 17 * In Gitlab steht draw.io zur Verfügung. Damit können Diagramme gezeichnet werden. [[https:~~/~~/www.drawio.com/blog/gitlab-wiki-integration>>https://www.drawio.com/blog/gitlab-wiki-integration]]
18 * Es gibt in Gitlab auch die Möglichkeit, Diagramme textuell zu beschreiben (Mermaid oder PlantUML) und dann generieren zu lassen: [[https:~~/~~/docs.gitlab.com/user/markdown/#mermaid>>https://docs.gitlab.com/user/markdown/#mermaid]], gerade bei Sequenzdiagrammen kann dies die Erstellung deutlich vereinfachen. Weitere Infos unter: [[https:~~/~~/docs.gitlab.com/user/markdown/#diagrams-and-flowcharts>>https://docs.gitlab.com/user/markdown/#diagrams-and-flowcharts]]
19
20 {{warning}}
21 **Achtung!**
22
23 * Es ist keine gute Idee mit dem Dokumentieren bis zum Schluss zu warten. Da sich Dinge aber im Laufe der Zeit noch ändern, sollte auch nicht zu viel Text schon vorher entstehen.
24 * Diagramme können zwar durch Reengineering gewonnen werden, es ist aber zu Präsentationszwecken keine gute Idee. Dann lieber die Strukturen abstrakter darstellen (nicht jede Methode, jede Klasse und jedes Attribut ist relevant!)
25 * Achtung! Wenn Sie Visual Paradigm verwenden, ändern Sie die Version nicht während des Projektes. I.d.R. sind die Modelle nicht beliebig austauschbar.
26 {{/warning}}
27
Marco Grawunder 3.1 28 = Architektur und Entwurf =
Marco Grawunder 1.1 29
30 * Zerlegung in Teilsysteme
31 * Bildung von Modulen (Klassen zu Gruppen zusammenfassen) Kopplung und Kohäsion beachten
32 * Festlegung der Architektur
33 * Abbilden auf Hardware
34 * persistente Datenverwaltung
35 * Festlegung von Entwurfsmustern
36 * Make or Buy (Verwendung von Frameworks)
37 * Dokument: System- und Objektentwurf
38 * Abgabe:
Marco Grawunder 2.1 39 ** [[Zwischenpräsentation>>doc:Main.Präsentationen.WebHome]] (siehe dort)
Marco Grawunder 1.1 40 ** zum Ende des Projektes finale Version
41 ** Dokumentation in einem extra Dokument (nicht auf GitLab verweisen)
Marco Grawunder 2.1 42 * Beachten: [[Anforderungen Dokumentation>>doc:Main.Dokumentation.WebHome||anchor="HAnforderungen:Dokumentation"]]
Marco Grawunder 1.1 43
44 = Anforderungen: Dokumentation =
45
46 Im Softwareprojekt muss am Ende zusätzlich zum eigentlichen Produkt ein Dokument abgegeben werden, welches im Wesentlichen die folgenden Aspekte enthalten sollte:
47
48 * Eine allgemeine Einleitung für das Dokument. Worum geht es und wie ist das Dokument aufgebaut.
49 * Grundsätzlich sollte jeder Abschnitt kurz eingeleitet werden und jeden Kapitel sollte eine kurze Zusammenfassung bekommen.
50 * Quellen müssen angegebenen werden, also z.B. nicht einfach Text von einer Web-Seite kopieren. Das kann u.U. als Plagiat ausgelegt werden...
51 * Eine Darstellung der ermittelten Anforderungen.
52 ** Dies umfasst mindestens die umgesetzten User-Stories (Sinnvoll: Die Akzeptanzkriterien für eine User-Story mit angeben.). Idealerweise werden die UserStories (siehe [[User-Stories>>doc:Main.Scrum.WebHome||anchor="HUserStories"]]) noch durch Anwendungsfälle unterstützt.
53 ** Ggf. eine Darstellung/Auflistung nicht umgesetzter User Stories. Die kann noch einmal zeigen, welche kreativen Ideen zeitlich nicht mehr umgesetzt wurden
54 ** Die Stories sollten möglichst gruppiert (z.B. nach Nutzerverwaltung, Hauptmenü/Lobby, etc.) werden.
55 * Darstellung der Realisierung
56 ** Allgemeine/Übergreifende Konzepte, z.B. wie wurde MVP realisiert
57 *** Darstellung der Architektur und Aufteilung des Gesamtsystems in Module
58 ** Für jedes Modul (Lobby, Chat, Game, ...):
59 *** Allgemeine Beschreibung
60 *** Im Client ggf. Screenshots
61 *** Darstellung der Klassen und Zusammenhänge der Klasse. Hier gerne auch ausschnittsweise, um ein besseren Verständnis zu bekommen. Vollständiges Klassendiagramm des Moduls im Anhang (auch hier nicht zwingend mit allen Attributen und Methoden).
62 **** Zur Darstellung der Zusammenhänge ist es i.d.R. sehr sinnvoll, Klassendiagramme ohne Attribute und Methoden zu verwenden.
63 *** Ganz wichtig ist auch die Darstellung der Abläufe (Dynamikdiagramme).
64 **** Wenn man die Kommunikation zwischen Klassen darstellen möchte: Sequenzdiagramm
65 **** Wenn man allgemeine Abläufe hat: Aktivitätsdiagramme
66 **** Wenn man unterschiedliche Zustände durchläuft: Zustandsdiagramm
67 **** Diagramme müssen erläutert werden. Ein Diagramm ohne Beschreibung ist faktisch nicht vorhanden. Es muss nicht alles im Detail erklärt werden, aber auf spezielle Besonderheiten oder die Verwendung von Pattern hingewiesen werden. Es sollte nicht einfach ein Diagramm an das nächste gehängt werden, sondern z.B. gesagt werden: „In dem Diagramm xy ist zu sehen, wie der grundsätzliche Ablauf eines Spielzugs ist. Dabei wird zunächst...“
68 **** Nicht immer ist offensichtlich, warum eine Lösung gewählt wurde. In diesem Fall sollten (Entwurfs-)Entscheidungen begründet/motiviert werden. Es ist grundsätzlich eine gute Idee, Dinge nicht nur „mitzuteilen“, sondern zu „erklären“.
69 **** Wenn man komplexere Algorithmen darstellen möchte, kann es besser sein, die Darstellung mit Pseudocode vorzunehmen.
70 *** Diagramme sollten an den Stellen im Text sein, an denen sie erläutert werden. Es muss vom Text aus auf die Diagramme verwiesen ("siehe Abb. X.Y") werden. Einfach alle im Anhang aufzulisten, macht keinen Sinn.
71 *** Hinweise: Man kann Diagramme in Gitlab auch textuell erzeugen: [[https:~~/~~/docs.gitlab.com/user/markdown/#diagrams-and-flowcharts>>https://docs.gitlab.com/user/markdown/#diagrams-and-flowcharts]] Macht es u.U. gerade bei komplexen Diagrammen einfacher.
72 ** Bei Spiel: Regelabweichungen darstellen und begründen
73 ** (Java-)Quellcode im Text möglichst vermeiden. Pseudocode kann für die Beschreibung von komplexeren Algorithmen verwendet werden.
74 ** **ACHTUNG**! Die Konzepte bitte so darstellen, als wenn sie nicht iterativ entstanden wären. Also keine "Verteilung" des Konzeptes auf Sprints. Wichtig ist, was am Ende herausgekommen ist.
75 ** Die Konzepte des Servers sollten mehr Aufmerksamkeit bekommen, als die den Clients.
76 ** Das Spiel ist das wichtigste im SWP, es sollte also im Realisierungskapitel den größen Umfang bekommen.
77 * Darstellung der Tests
78 ** Nach welchem Vorgehen wurde getestet?
79 ** Welche Tests gibt es?
80 *** Hinweis: Hier nicht jeden einzelnen Unit-Test aufführen, das ist unnötige Arbeit!
81 ** Wie sieht die Testabdeckung aus?
82 ** Was wurde nicht automatisiert getestet und wie wurde sichergestellt, dass die Funktionalität trotzdem korrekt ist?
83 ** Beschreibung des (mindestens einmal) durchgeführten gruppenweiten Codereviews. Aus Gründen der Bewertung ist es u.U. sinnvoll, Pull-Request mit beispielhaften Reviews in Git nicht zu löschen.
84 * Darstellung des durchgeführten Projektmanagements
85 ** Rollen
86 ** Arbeitsweise
87 ** Meilensteine
88 ** Rückblick über die Sprints/ Projekttagebuch
89 ** Verwendete Frameworks, Bibliotheken und Tools
90 * Ausblick: Was könnte man noch machen? Hier auf eine sinnvolle Reihenfolge achten
91 * Fazit:
92 ** Rückblick auf das vergangene Jahr.
93 ** Was hat man gelernt?
94 ** Was hat gut funktioniert, was weniger gut?
95 ** Feedback zum Software Projekt allgemein (es geht um die Durchführung der Veranstaltung als solches, d.h. z.B. was kann an der Veranstaltung als solches verbessert werden):
96 *** SWP Retrospektive: „Do More“, „Do Less“, „Keep Doing“, „Start Doing“, „Stop Doing“
97 ** NEU: Was würdet ihr (anonym) den Studierenden in den Folgejahren empfehlen?
98 * Anhang:
99 ** Ggf. vollständige Klassendiagramme (Ohne weitere Erläuterung)
100 ** Protokolle und andere im Laufe der Zeit entstandene Dokumente in speziellen Ordner hinterlegen. **Nicht (mehr) in das Dokument mit aufnehmen**, das ist nur unnötige Arbeit.
101 * Glossar mit Begriffen des Gegenstandes/Spiels
102 * Index  (Falls Dokument mit LaTeX erstellt)
103
104 Ich werde immer wieder gefragt, wie viele Seiten die Dokumentation haben muss. Das lässt sich so pauschal leider nicht sagen, denn das hängt zum einen natürlich massiv von der verwendeten Vorlage ab, zum anderen aber auch davon, welches die aktuelle Aufgaben gewesen ist. Zur Orientierung kann man jedoch sagen, dass die typische (gelungene) (LaTeX-basierte-)Dokumentation in den letzten Jahren immer so in dem Bereich von 80 bis 100 Seiten (inkl. Anhängen und Bildern) gelegen hat. Es macht nun aber keinen Sinn, die Seitenanzahl künstlich durch "unnötigen" Inhalt aufzublähen. Ich schaue schon sehr genau darauf, wie gelungen und vollständig die oben genannten Punkte abgehandelt werden.
105
106 Zum Produkt selber noch notwendig:
107
108 * Eine Spielanleitung: Über die Regeln des Spiels hinausgehende Beschreibung, wie die Bedienung erfolgt
109 * Wie erfolgt die Installation und die Konfiguration?
110
111 Im Git-Repository gibt es eine Dokumentationsvorlage für LaTeX.
112
113 {{success}}
114 **Hinweis:**
115
116 * Falls es Widersprüche zwischen der Vorlage und dem Text hier im Wiki gibt, bitte eine kurze Nachricht. Im Zweifelsfall zählt der Inhalt aus dem Wiki.
117 * Falls etwas nicht korrekt funktioniert, bitte auch eine kurze Nachricht. Ich kümmere mich.
118 * Gruppen, die ihre Dokumentation auch im Git pflegen wollen, können mir einen Nachricht schicken und ich richte das Repo dann passend ein.
119 * [[https:~~/~~/gitlab.swl.informatik.uni-oldenburg.de/SPB/dokumentation>>https://gitlab.swl.informatik.uni-oldenburg.de/SPB/dokumentation]]
120 {{/success}}
121