Dokumentationsvarianten

Prinzipiell gibt es drei Arten von Dokumentationen, die Bibliotheken begleiten:

Referenz-Manuals

sind mit Abstand die wichtigste Art von Dokumentation. Sie sollten ein gutes Nachschlagen ermöglichen und sind typischerweise nach Modulen, Klassen oder Typen geordnet. Um praktikabel zu sein, sollten sie ähnlich strengen Formalismen unterworfen werden, wie sie bei dem Programmtext Anwendung finden. Sehr geeignet ist z.B. die Struktur der UNIX-Manualseite mit ihren festen Abschnitten von NAME bis BUGS.

Guides

führen in die Bibliothek oder in einen Teilbereich der Bibliothek umfassend ein. Hier liegt der Schwerpunkt in der didaktischen Aufbereitung und weniger bei der guten Nachschlagbarkeit. Zwar kann letzteres teilweise auch durch einen umfangreichen Index geleistet werden, jedoch nie so gut wie eine ausgefeilte Manualseite, die zuverlässig alle relevanten Informationen zu der Verwendung eines Moduls, Klasse oder Typs geben sollte. Die didaktische Aufbereitung sollte insbesondere auch das Modell und die Prinzipien hinter der Bibliothek (oder Teilen davon) erläutern, so daß Aufbau und Stil der Bibliothek vertrauter werden.

Tutorials

erlauben einen ersten Einstieg in die Benutzung einer Bibliothek, bei dem die Betonung auf leichte Erfaßbarkeit liegt auf Kosten der vollständigen Abdeckung. Häufig gibt es auch Tutorials zu einzelnen Bibliotheksbereichen.

Abbildung 4.1: Online-Dokumentation der Sather-Bibliothek

Leider gibt es nur in den allerwenigsten Fällen alle drei Varianten. Grundsätzlich sollte es Referenz-Manuals geben, weil

• sie am leichtesten korrigiert, ergänzt und angepaßt werden können, wenn Änderungen bei den Quellen erfolgen. Einem Entwickler von Bibliotheksmodulen kann die Pflege der zugehörigen Manualseite zugemutet werden, jedoch typischerweise nicht die von Guides und Tutorials, da dort der Aufwand jeweils ungleich größer ist und sie daher (bei kommerziellen Bibliotheken) von technischen Autoren gepflegt werden.

• nur sie am schnellsten dem erfahrenen Bibliotheks-Nutzer die gewünschten Informationen liefern können.