BWINF
Tipps
Dokumentation

Dokumentation

Die Bewertung der Einsendungen basiert hauptsächlich auf eurer Dokumentation. Sie ist also genauso wichtig (wenn nicht sogar wichtiger) als euer Programm. Es ergibt daher Sinn, viel Zeit in eine gute Dokumentation zu investieren. Insbesondere sollte man auch früh genug mit der Dokumentation anfangen und nicht den Aufwand unterschätzen. Gerade in der zweiten Runde kann es hilfreich sein, die Lösungsidee vollständig zu formulieren, bevor man überhaupt mit der Implementierung beginnt. Die Implementierung kann dann zeitgleich mit der Formulierung der Umsetzung erfolgen.

Wenn unklar wird, was zur Dokumentation gehört, kann man sich gut an folgende "Richtlinien" orientieren:

Es geht bei der Dokumentation darum, dass [die Bewertenden] schnell und einfach überblicken und überprüfen können, ob das Programm korrekt arbeitet. Das ist auch bei der Dokumentation der Beispiele und deren Lösungen so. Wenn dazu nur die Ausgabe reicht, nimmst du nur die Ausgabe. Wenn es sinnvoller ist, Zwischenschritte zu dokumentieren, um die Funktion oder eine Besonderheit des Programmes hervorzuheben, ist es ebenfalls sinnvoll, dies zu dokumentieren.

Nehme also alle Dokumentationen immer in diesem Sinne vor: Erleichtere ich damit der bewertenden Person das Verständnis meines Programms? Kann man dadurch gut nachvollziehen, was mein Programm macht? Kann ich durch mein Beispiel vielleicht die Leistungsfähigkeit oder Grenzen meines Verfahrens aufzeigen? Wichtig ist immer die leichte Nachvollziehbarkeit für die Bewertenden.

Struktur der Dokumentation

Für jede Aufgabe muss eine eigene Dokumentation in Form einer pdf-Datei erstellt werden, welche aus vier Teilen, Lösungsidee, Umsetzung, Beispielen und Quellcode bestehen soll.

Lösungsidee

In dem Abschnitt Lösungsidee solltet ihr das vorliegende Problem definieren und formalisieren sowie Algorithmen und Datenstrukturen erläutern, mit denen ihr das Problem löst. Es geht also vor allem darum, wie und warum ihr so vorgeht, und nicht, wie ihr eure Ideen konkret in einer Programmiersprache umsetzt. Eine hilfreiche Richtlinie ist, dass ihr hier keine Programmelemente wie Variablen oder Funktionen erwähnen solltet.

Oft ist es vorteilhaft, eure Ideen mathematisch zu formalisieren. Das ist zwar nicht zwingend notwendig, kann aber helfen, eure Gedanken präziser auszudrücken. Ähnlich sind Fachausdrücke (bspw. "Tiefensuche") im Kontext oft besser verständlich als eine umständliche Beschreibung (bspw. "Wir gehen jetzt jeden Knoten im Graphen durch und gehen immer weiter nach unten.").

Umsetzung

Nachdem ihr eure Lösungsidee beschrieben habt, solltet ihr erläutern, wie sie konkret im Programm implementiert wird. Dazu gehören z.B. welche Klassen und Methoden/Funktionen ihr erstellt habt und was diese genau tun. Eine graphische Darstellung eures Programms z.B. mithilfe eines Klassendiagramms könnte manchmal hilfreich sein.

Beispiele

Es ist wichtig, dass man sieht, dass euer Programm auch wirklich (korrekt) funktioniert. Deshalb solltet ihr euer Programm mit allen vorgegebenen Beispielen testen und dabei die Ergebnisse in der Dokumentation festhalten. Für jedes Beispiel soll die komplette Programmausgabe in der Dokumentation eingebunden sein, sofern nicht auf dem Aufgabenblatt oder der BWINF-Seite ausdrücklich anders vermerkt. Sollte die Ausgabe für ein bestimmtes Beispiel sehr lang sein (e.g. über eine Seite), setzt euch bitte mit BWINF (z.B. über das Forum oder den Discord-Server) in Verbindung, um eine offizielle Antwort zu bekommen, ob und ggf. wie ihr kürzen dürft.

Fehlende Beispiele führen immer zu Punktabzügen, da die Bewerter ohne die Beispiele die Korrektheit der Lösung nicht überprüfen können.

Es ist darüber hinaus empfehlenswert, insbesondere interessante und eigene Beispiele sowie dazugehörige Programmausgaben kurz zu kommentieren und die reale Laufzeit für diese Beispiele anzugeben. Wenn ihr weitere eigene Beispiele habt, solltet ihr diese dann unbedingt mit Kommentaren versehen, welche Sonderfälle sie genau abdecken.

Beispiele und Ausgaben sollen sowohl in der Dokumentation als auch als separate Text-Dateien eingesendet werden, sofern nicht anders angegeben.

Quellcode

Der Quellcode gehört zum letzten Abschnitt eurer Dokumentation und enthält die wichtigsten Teile eures Programms. Wichtig sind insbesondere diejenigen Teile des Quelltexts, in welchen die Lösungsidee umgesetzt ist, das heißt die zentralen Algorithmen und Datenstrukturen. Hingegen sind Ein-/Ausgaben meistens nicht wichtig und gehören nicht zu diesem Abschnitt.

Sollte die Kompilierung eures Programms besondere Anweisungen benötigen, so sind diese auch in diesem Abschnitt anzugeben.

Zitate

Eure Dokumentation ähnelt einer wissenschaftlichen Arbeit, weshalb ihr auch an Regeln halten müsst, die sonst bei einer wissenschaftlichen Arbeit üblich sind. Dazu gehört, dass ihr richtig zitiert.

"Alle Inhalte, die aus anderen Arbeiten stammen, müssen als Zitat gekennzeichnet werden." [1]

Zu Zitaten gehören direkte und indirekte Zitate. Konkret dazu findet ihr in diesem Artikel (opens in a new tab).

Es ist überhaupt nicht schlimm, dass ihr die Arbeiten von anderen in eurer eigenen Arbeit verwendet. Für BWINF kommt es insbesondere darauf an, dass ihr in eurer Dokumentation zeigt, dass ihr das zitierte Werk verstanden habt. Also solltet ihr genau begründen, wie die zitierte Arbeit beim Lösen der konkreten Aufgabe hilft.

Die Nutzung von weiteren Bibliotheken in eurem Programm sollte ebenfalls dokumentiert und die Quelle der Bibliothek zitiert werden.

[1] Hahner, S. (2021). Wissenschaftliches Schreiben – Schnelleinstieg. Github. https://github.com/sebinside/WissenschaftlichesSchreiben-Schnelleinstieg/releases/download/v1.0.2/Schnelleinstieg.pdf (opens in a new tab).

Vorlagen

Für die Dokumentation bietet BWINF Vorlagen an, die ihr hier herunterladen könnt: https://git.bwinf.de/bwinf/vorlagen.git (opens in a new tab).

Ein paar Einsendungen der vergangenen Jahre findet ihr unter

Das Urheberrecht der oben verlinkten Repos liegt bei den jeweiligen Autoren.

EndrundeCheckliste - Abgabe