Next: Repräsentierung der Dokumentation
Up: Dokumentation von Bibliotheken
Previous: Dokumentation von Bibliotheken
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.
Next: Repräsentierung der Dokumentation
Up: Dokumentation von Bibliotheken
Previous: Dokumentation von Bibliotheken
Andreas Borchert
2/2/1998