Originale Form der Dokumentation

Hierbei gibt es zwei Schulen: Die eine Seite bringt die Referenz-Dokumentation direkt in den Quellen unter, und die andere zieht es vor, dies in separaten Dokumenten zu verwalten. Wichtig ist, daß die Verbindung von Quellen mit der Referenz-Dokumentation nicht mit literate programming zu verwechseln ist, wie Knuth es für TEX eingeführt hat, da eine Referenz-Dokumentation nur beschreibt, wie ein Modul zu benutzen ist und nicht wie sein Innenleben funktioniert. Für beide Schulen gibt es gute Gründe:

 

Abbildung 4.4:   Referenzseite eines Java-Moduls

• Wenn der Programmtext und die zugehörige Referenz-Dokumentation ein gemeinsames Dokument bilden, ist die Gefahr geringer, daß beide nicht miteinander synchronisiert sind. Außerdem wird damit dem Programmierer unmittelbar die Verantwortung zur Verwaltung der Referenz-Dokumentation übertragen.
• Andererseits sind in vielen Fällen die textuellen Aufbereitungsmöglichkeiten innerhalb der Programme sehr beschränkt - so ist es bei einigen Systemen nicht möglich, Tabellen unterzubringen. Natürlich gibt es auch hierfür Lösungen: So ist bei einigen Oberon-Systemen die Einfügung beliebigen formatierten Textes bishin zu Animationen möglich (entsprechende Arbeiten gibt es z.B. von Mössenböck) und alternativ könnten auch textbasierte Formatierungssysteme wie z.B. TEX eingebettet werden. Allerdings ist es nicht ganz einfach, diese Varianten ohne weiteres in HTML zu verwandeln.
• Häufig wird die Referenz-Dokumentation modifiziert, ohne daß der eigentliche Programmtext geändert werden muß, z.B. um den Text didaktisch besser aufzubereiten oder ganz schlicht Schreibfehler zu korrigieren. Dies führt dann dazu, daß das betroffene Modul und alle davon abhängigen Module vollkommen unnötig frisch übersetzt werden müssen.