Dokumentationen verfassen

[Michael Schröpl]

Hi Christian,

Oder php.net oder mysql.com ....

bei Dokumentationen über große Programmsysteme gibt es diverse auf diesen Zweck zugeschnittene Konzepte.

Eines davon - schon recht alt, aber als Beispiel gut zu gebauchen - ist das Konzept "Web" von Donald Knuth. (Nein - mit dem World Wide Web hat das nichts zu tun.)
Die 'Quelltexte' eines solchen Systems enthalten nicht nur Anweisungen einer entsprechenden Programmiersprache, sondern gleichzeitig die Dokumentation der entsprechenden Funktionseinheiten (Module etc.).
Aus den entsprechenden Dateien werden dann mit separaten Tools die einzelnen 'Varianten' überhaupt erst mal generiert - einerseits der dann reine Programmquelltext, andererseits die hochwertig aufbereitete Dokumentation.
Bei Knuth's "Web" heißen diese Tools "tangle" und "weave" - und die generierte Dokumentations-Form ist natürlich TeX (was aber nur am konkret verwendeten Tool liegt - heute könnte es fast genauso gut HTML sein).
Perl unterstützt anscheinend ein ähnliches Konzept mit seinen PODs (und wahrscheinlich noch einiges mehr, das ich selbst gar nicht kenne).

Sinn der Sache ist, daß derjenige die _inhaltliche_ Seite der Dokumentation übernimmt, der versteht, was er schreibt - während die technische Seite der Präsentation davon stark abgegrenzt wird und Layout-Spezialisten (oder eben sogar Programmen) überlassen werden kann.
Außerdem steht dann die Dokumentation insbesondere dort, wo man sie braucht, wenn man das Programm ändern muß - nämlich im Programm selbst. Und derjenige, der das Programm pflegt, braucht kein separates Werkzeug für die Erstellung der Dokumentation ...
Hast Du schon mal einen Umzug einer Firma auf ein anderes Betriebssystem mitgemacht? Es gab auch schon vor Windows Dokumentationen ... in Formaten, die Du Dir heute gar nicht mehr vorstellen kannst. Und wenn sich die Dokumentationsplattform ändert, die Entwicklungsplattform aber nicht, wer portiert dann die vielen hundert Dateien der Dokumentation auf das neue Dateiformat?

Ich kann mir vorstellen, dass die Texte in einer Datenbank abgelegt werden, und dann mit einem Programm ausgelesen werden und zu einer Dokumentation zusammengefügt werden.

Auch das kann man sicher tun. Ersetze Datenbank durch XML, Edifact oder beliebige weitere Meta-Formate, dann hast Du weitere Möglichkeiten.

Ich kann mir nicht vorstellen, das das alles als statische HTML-Seiten geschrieben wird, da die Wartung und Pflege dann sehr schwer fällt.

Hier ist mir der kausale Zusammenhang dieser beiden Aussagen nicht zwingend klar.

Eine saubere Trennung zwischen Inhalt und (einheitlichem) Layout ist gerade bei Verwendung von CSS einerseits und der Generierung von HTML-Dokumenten (SSI, PHP, Makro-fähige Editoren etc.) andererseits sehr wohl möglich.
Was dafür allerdings notwendig ist, das ist die Beherrschung sowohl der inhaltlichen als auch der präsentationstechnischen Skills durch dieselbe Person, da beide in derselben Abstraktionsebene ausgedrückt werden - nämlich im Quelltext.
Andererseits kann man durchaus immer noch Teile der Funktionalität auslagern - beispielsweise kann ein Spezialist die Pflege aller CSS-Definitionen übernehmen, während die Autoren lediglich HTML und die für dieses Projekt vorgegebenen Klassennamen verwenden können müssen ...

Es gibt viele Wege, die hier zum Ziel führen - weil es viele verschiedene Ziele gibt. Diese hängen nicht unwesentlich von den bereits verfügbaren Skills der teilnehmenden Personen ab.

Viele Grüße
      Michael