Glossar in der Projektdokumentation

Häufig sehe ich in Projektdokumentationen ein Glossar. Grundsätzlich ist das auch eine gute Idee, aber in vielen Arbeiten, die ich gelesen habe, enthält das Glossar nur allgemein bekannte Begriffe, die nicht in ein Glossar zu einer technischen Dokumentation gehören.

Was wissen die Prüfer?

Du kannst davon ausgehen, dass die Prüfer grundlegende Begrifflichkeiten aus der Informatik kennen. Du musst ihnen z.B. nicht erklären, was eine GUI ist oder was Objektorientierung bedeutet. Dazu zähle ich auch sehr spezielle oder moderne Begriffe wie z.B. Lambda-Ausdrücke oder Interfaces.

In das Glossar gehören solche Begriffe, die versierten Informatikern (= den Prüfern) sehr wahrscheinlich nicht bekannt sind. Hauptsächlich geht es dabei um Begriffe aus deinem Unternehmen. Allgemeine Begriffe aus der Informatik musst du nicht erklären.

Wo ziehe ich die Grenze?

Das Problem ist jetzt natürlich, wie man entscheidet, was allgemein bekannt sein sollte. Im Prinzip kannst du alles aus dem Glossar streichen, das du selbst in der Berufsschule gelernt hast. Diese Inhalte sollten deinen Prüfern bekannt sein.

Sobald es allerdings um Programme, Konzepte, Fachbegriffe usw. aus deiner eigenen Domäne geht, ist die Lage etwas anders. Die Prüfer können sich nicht in allen erdenklichen Fachgebieten, für die die Unternehmen der Prüflinge Software entwickeln, auskennen.

Wir haben teilweise völlig unterschiedliche Industrien in den Prüfungen. So kann es sein, dass der erste Prüfling in einer Versicherung arbeitet und der zweite programmiert Software für einen landwirtschaftlichen Betrieb. Und jede dieser Domänen zu beherrschen ist nicht möglich.

Auch wenn du selbst dein alltägliches Umfeld natürlich in- und auswendig beherrschst, gilt das für die Prüfer nicht. Und deine Aufgabe in der Projektdokumentation ist es, dich in die Lage eines „Unwissenden“ zu versetzen, der von deinem Unternehmen und Projekt lediglich die 15 Seiten Fließtext kennt (oder wie viele Seiten deine IHK auch immer vorgibt).

Geh also nicht davon aus, dass den Prüfern die Einzelhandelsbranche, dein selbst entwickeltes ERP-System oder die internen Abläufe eines Logistikunternehmens bekannt sind. Diese Informationen gehören eventuell in ein Glossar.

Wann ein Glossar sinnvoll ist

Versuche vor dem Erstellen eines Glossars aber erst einmal so gut es geht die Fachbegriffe und Gegebenheiten deiner Domäne in der Projektdokumentation zu erklären. Es ist deine Aufgabe, den Prüfern dein Projektthema verständlich zu machen. Und gegebenenfalls ist hierfür auch ein Glossar sinnvoll. Aber das erfordert ein Hin- und Herblättern beim Lesen und erhöht nicht unbedingt das Verständnis des Textes. Wenn ich deine Erklärung einfach runterlesen kann, ist das sicherlich besser!

Insbesondere, wenn du zentrale Begriffe immer wieder benutzt, weil zum Beispiel deine Entitäten oder Klassen entsprechend benannt wurden, kann es sinnvoll sein, diese Begriffe im Glossar zu hinterlegen, damit die Prüfer beim Lesen der Dokumentation eine schnelle Möglichkeit haben, sie an einer zentralen Stelle nachzuschlagen, und nicht durch alle bisher gelesenen Seiten suchen müssen.

In meiner eigenen Projektdokumentation habe ich damals einige zentrale Begrifflichkeiten der Versicherungsmathematik hinterlegt, die ich ständig benutzt habe. Denn wenn ich sie im Fließtext erklärt hätte, wäre er zu lang geworden.

Beispiele: Rentenbarwert, Kommutationswert, diskontierte Lebende, Sterbetafel.

Ja, die Krankenversicherung ist schon ein heißes Pflaster! 😉

Technik im Glossar

Darüber hinaus ist es manchmal auch sinnvoll, technische Informationen in ein Glossar zu schreiben. Wenn du zum Beispiel mit einer exotischen Programmiersprache arbeitest oder wie z.B. bei SAP mit kryptischen Modulnamen oder Interna der Plattform hantierst, ist es sinnvoll, diese Dinge in einem Glossar zu erklären.

Die grundlegenden Funktionen von Programmiersprachen werden die Prüfer auch bei ihnen unbekannten Sprachen verstehen können (z.B. Schleifen und Verzweigungen). Aufrufe auf interne Programme, deren Sinn sich nicht anhand des Namens erschließt (Beispiele sind die zahlreichen Transaktionen X4711 in SAP), kann ein Prüfer jedoch nicht ohne Hintergrundwissen verstehen.

Und nein: Nicht alle Prüfer beherrschen SAP! Ich selbst gehöre auch zu dieser Gruppe. Und ich bin sogar (ein wenig) froh darüber! 😉

Fazit

Ein Glossar ist sinnvoll, um Begrifflichkeiten, die du nicht als allgemein bekannt bei Prüfern voraussetzen kannst, an einer zentralen Stelle zu definieren. Geh davon aus, dass die Prüfer technisches Know-How mitbringen und auf dem neuesten Stand hinsichtlich Programmiersprachen und Paradigmen sind.

Oftmals kann ein Glossar durch eine bessere Formulierung in der Problembeschreibung überflüssig gemacht werden. Im Zweifel würde ich immer versuchen, den Fließtext besser verständlich zu schreiben, als ein Glossar anzuhängen. Den wertvollen Platz, den du mit dem Glossar belegst, kannst du besser für fachliche Inhalte verwenden (z.B. Diagramme, Pflichtenheft, Zeitplanung).


Hast du in deiner Dokumentation ein Glossar benutzt? Wenn ja, welche Begriffe hast du dort aufgeführt?

Weitere Infos zur Projektdokumentation

Du suchst noch mehr Tipps rund um die Projektdokumentation? Dann schau doch mal in diese Artikel- und Podcast-Kategorie: Alle Artikel rund um die Projektdokumentation.

Kennst du schon meine Microsoft Word-/LibreOffice-Vorlage für die Projektdokumentation? Unter dieperfekteprojektdokumentation.de kannst du sie herunterladen.

Und wenn du dich für meinen Newsletter einträgst, kannst du dir jetzt sofort meine Checkliste für die Projektdokumentation herunterladen.

Checkliste für die Projektdokumentation

Jetzt anmelden!

Polyglot Clean Code Developer
About the Author
Ausbildungsleiter für Fachinformatiker Anwendungsentwicklung und Systemintegration, IHK-Prüfer und Hochschuldozent für Programmierung und Software-Engineering.

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert

To create code blocks or other preformatted text, indent by four spaces:

    This will be displayed in a monospaced font. The first four 
    spaces will be stripped off, but all other whitespace
    will be preserved.
    
    Markdown is turned off in code blocks:
     [This is not a link](http://example.com)

To create not a block, but an inline code span, use backticks:

Here is some inline `code`.

For more help see http://daringfireball.net/projects/markdown/syntax