nicht angemeldet
Hi,
Wie handhabt ihr das? Kennt ihr vielleicht Quellen, in denen beschrieben wird, wie man Dokumentationen für die verschiedenen Zielgruppen zu schreiben hat?
"Zu schreiben hat" gibt es bei freier Software nicht (bei unfreier Software sollte es das auch nicht geben ;-) Schau Dich halt mal um ... ich - so ganz persoenlich - handhabe das ungefaehr so:
-
fast alle meine Programme haben eine option "-h" fuer help, die alle Optionen etc. in Kurzform anzeigt.
-
"Kleine" Sachen (z.B. shell scripts) bekommen eine Mini-Dokumentation im header. Ich gehe einfcah davon aus, dass jemand, der ein shell-script einsetzt, auch mal reinschaut ;-)
-
"Mittelgrosse" Dinger bekommen ein README-file (plain text), dessen Struktur grob an eine manpage angelehnt ist.
-
"Grosse" Sachen bekommen eine ausfuehrliche Dokumentation, ueblicherweise aufgeteilt in eine "Technical Reference" (fuer den Sysadmin) und ein "User Manual" ('Wie benutzt man das Ding'). Diese Dokumentation schreibe ich dann bevorzugt in LyX bzw. LaTeX und lege das PDF bei.
-
In allen Faellen steht ganz am Anfang ein kurzer Absatz, der in einfachsten Worten erklaert, was das Programm kann, evtl. was es NICHT kann, und wer damit (vermutlich ;-) etwas anfangen kann. Das liest sich dann manchmal so:
"... If you are not working with mass spectrometry, if you are neither chemist nor physicist, then this program is probably not for you ;-)"
Gruss aus Lausanne!
- Joerg