Dokumentation (freier) Software

[Alexander Brock]

Hallo Freunde des gehobenen Forumsgenusses,

Da ich selbst freie Software schreibe und (inzwischen auch) dokumentiere würde ich gerne von euch wissen, was alles in eine solche Dokumentation gehört.
Im Moment schreibe ich für mein Lieblingsprojekt zwei Dokumentationen:
Eine in PHPDoc und eine für Leute, die die Software einfach nur einsetzen wollen ohne zu wissen, wie sie funktioniert: Benutzer-Dokumentation.

Wie handhabt ihr das? Kennt ihr vielleicht Quellen, in denen beschrieben wird, wie man Dokumentationen für die verschiedenen Zielgruppen zu schreiben hat? Seht ihr in meinen Dokumentationen Fehler / Sachen, die ihr anders machen würdet?

Gruß
Alexander Brock

[Joerg]

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

[lina-]

moin Alexander :)

Seht ihr in meinen Dokumentationen Fehler / Sachen, die ihr anders machen würdet?

Fehler? Der einzige Fehler, den man bei der Doku machen kann, ist, sie nicht zu schreiben ;)
Nein im Ernst - es gibt glaube ich keine wirklichen Richtlinien für Doku. Ich finde deine User-Doku sehr gelungen. Falls es in Frage kommt noch ein Tipp: Unsere Kunden haben sich sehr über die FAQ und die How-To gefreut. Da kamen die ganz allgemeinen Dinge rein (wie z.B. "wie konfiguriere ich das Programm, wenn ich dieses Verhalten erreichen möchte" oder "Die rechte Ansicht ist ganz verschoben - was nun?")

liebe Grüße aus Berlin
lina-