Sachliche und informative Diskussion über das Schreiben von Dokumentationen

Hallo,

nachdem mein anderer Thread so unsanft aus dem Leben gerissen wurde möchte ich mich hier bei euch erkundigen, wie man gute Dokumentationen schreibt. Ich kenne das so: Wenn ich fremde Dokumentationen lese, dann ärgere ich mich oft dass das was ich suche nicht explizit erklärt ist und ich mir das umständlich zusammensuchen muss. Oder dass ein allgemeiner Überblick fehlt; in den schlimmsten Fällen geht das so weit dass ich z.B. nicht weiß ob "foo=bar" jetzt ein Kommandozeilenparameter, eine Option im Konfigurationsfile, eine Eingabe oder etwas ganz anderes ist.

Auf der anderen Seite stand ich schon ein- oder zwei Mal in der Verlegenheit selbst eine Doku schreiben zu müssen (Programmieren / Dokuschreiben ist nicht meine Haupttätigkeit), und ich fürchte dass die Unglücklichen, die sie lesen müssen, ebenfalls vor solchen, wenn nicht gar viel schlimmeren Problemen stehen. Oft hat mir beim Schreiben auch ein Leitfaden gefehlt, was alles in eine Doku rein muss und wie ich überprüfen kann ob sie vollständig und verständlich genug ist.

Folgender Artikel (http://magazine.redhat.com/2007/01/30/how-to-write-really-good-documentationfour-rules-and-an-axiom/) zu diesem Thema gibt fünf Regeln an, aber bis auf Regel Null sind das mehr deskriptive und nicht instruktive Aussagen.

http://jacobian.org/writing/great-documentation/what-to-write/ ist schon etwas expliziter, vor allem die "30 Minutes Rule" finde ich einen guten Richtwert.

Also: Wie schreibt ihr, die ihr erfahrener seid als ich, gute Dokumentationen?

edit: link klickbar gemacht

DEvent

Ein Problem ist auch, für was für ein Publikum man schreibt. Die Linux Manpages sind schon für ein Publikum, dass sich mit Linux auskennt. Man schreibt auch oft für ein Publikum für das man sich dazu zählt. Also jemand, der ein Systemadministrator ist und ein Systemtool geschrieben hat, würde eine Dokumentation für Systemadministratoren schreiben. Man verwendet Begriffe, die in seinem Umfeld genau definiert sind. Nun trifft das Problem auf, dass ein anderes Publikum nichts mit der Dokumentation anfangen kann.

Z.B. die manpage von ps(1).

ps displays information about a selection of the active processes.

Was ist aber nun ein "process"? In Unix ist alles ein Prozess, jemand der nur Windows benutzt hat wird sich nun wundern ob ein Prozess eine Anwendung ist.

Was ich noch gerne anfügen würde sind Beispiele von guter und schlechter Dokumentation:

gnuplot:

help foo

gibt eine sehr gute Dokumentation. Ein Problem bei Kommandozeilen-Tools im Gegensatz zu GUI ist oft dass die Menge der validen Eingaben im vergleich zur Menge der möglichen Eingaben bei ersteren unglaublich klein ist: In jeder vernünftigen GUI ist ein "Syntax Error" oder ein "unbekanntes Schlüsselwort" ausgeschlossen, weil Datentypen wie ints, strings, enums durch die Bedienelemente repräsentiert und erzwungen werden. In Gnuplot ist aber eine ausreichende Anzahl von Wörtern, die keine Kommandos sind, mit einem Dokueintrag verlinkt. Dieser Eintrag hat dann auch nicht nur eine abstrakte Definition sondern auch Beispiele, die das schnellere Verständnis erleichtern. *
Wenn man sich bereits in einem CLI wohlfühlt ist Gnuplot gut dokumentiert. Wenn man GUI gewohnt ist, wird es einen verwirren (hat es mich zumindest damals).
Noch besser ist es, wenn das Programm tab-completion oder äquivalente Mechanismen bereitstellt, ähnlich wie es ipython für python-code, oder bash für viele Programme tut. Wobei es hier immer noch Verbesserungspotential gibt.

DEvent schrieb:

Ein Problem ist auch, für was für ein Publikum man schreibt.

Wie der Mensch im meinem zweiten Link schreibt ist es manchmal sogar gut wenn der unqualifizierte Benutzer schnell merkt dass die Sache nichts für ihn ist bzw. dass er sich erst anderweitig informieren muss. Problematisch wird es, wenn von Benutzern eine höhere Qualifikation gefordert wird als eigentlich nötig wäre, weil die Dokumentation zu kompliziert formuliert ist.

* Ein Beispiel dafür ist die manpage zu man: sudoers, wo mal eben schnell EBNF eingeführt wird um die Syntax zu erklären. Einerseits gut, weil formal richtig, andererseits: ist das wirklich nötig? Zum glück ist noch ein ausführlicher "Examples" - Abschnitt vorhanden.

rüdiger

Ich finde ausführliche Beispiele sind wichtig. Wie du schon gesagt hast, hat man bei eine Doku immer das Komplexitätsproblem. Für die einen ist die Doku immer zu kurz und oberflächlich und die anderen beschweren sich, dass sie zu umfangreich ist und man nicht zum Ziel kommt. Mit Beispielen kann man eine umfangreiche Doku schreiben und die Leute - die mal eben eine Kleinigkeit wollen - kommen dann hoffentlich mit den Beispielen klar. Außerdem wird durch die Beispieles vieles verständlich, vorallem wenn man mit der Nomenklatur nicht vertraut ist.

Das beste ist es natürlich, wenn man ein System hat, wo man die Dokumentation gleich integriert. Konkret fällt mir da zB Emacs ein, wo einfach jede Funktion direkt mit einer Doku versehen wird oder TeX wo der Quellcode gleich die Dokumentation ist (auch wenn "Literate Programming" natürlich so eine Sache ist).

nman

Achtung, langer Post.

Eines der größten Probleme beim Schreiben von Doku ist, dass es für Dich als Autor und somit Experten im Umgang mit Deiner Software so verflucht schwer ist, Dich in die Rolle des unbedarften Benutzers hineinzuversetzen.

Auch wenn es sich nicht irgendwie speziell an Softwareentwickler richtet, finde ich "Made To Stick" toll, wo unter anderem dieser "Curse of Knowledge" erklärt wird:
Made to Stick | ISBN: 1400064287

(Auch die Ausführungen zu Metaphern, Analogien und Struktur von Erklärungen sind sehr gut auf Doku anwendbar.)

Wie schon gesagt:

Eine eingängige Kurzbeschreibung ist wichtig.
Gute Beispiele sind wichtig. Wenn nicht verfügbar sind schlechte immer noch besser als gar keine. (Wie war das nochmal mit "Documentation is like sex"?)
Zu guten Beispielen gehört: Sowohl winziges Minimalbeispiel als auch etwas ausführlicheres, längeres Beispiel. Keine künstlichen, konstruierten Sachen, sondern tatsächliche Anwendungsfälle.
Die Kenntnis der Zielgruppe ist wichtig. (Ich hasse Doku, wo ich mir aus Kochrezept-artigen Einzelschritten zusammenreimen muss, welchen Highlevel-Schritt der Autor mich gerade verrichten lassen möchte.)
Nachdem ich auch sehr oft mit Projekten zu tun habe, die nur sehr spärlich oder gar nicht dokumentiert sind und Sourcen lesen muss: Ich mag es, wenn a) irgendwo grob das Design erklärt wird, b) die Sourcen lesbar genug sind, um zügig nachvollziehen zu können, wie eine Library funktioniert und c) die Testcoverage gut ist (siehe nächster Punkt).
Wenn aktuelle Tests vorhanden sind, sind diese häufig zugleich auch sehr gut als Dokumentation geeignet.

In vielen Fällen finde ich übrigens die Manpages diverser BSDs deutlich besser, als die von GNU/Linux. Beispiel: whois. In der GNU/Linux-whois-Manpage ist von Object und Host die Rede und es wird nicht wirklich klar, was was sein soll:

NAME
       whois - client for the whois directory service

SYNOPSIS
       whois  [  -h  HOST  ]  [ -p  PORT ] [ -aCFHlLMmrRSVx ] [ -g SOURCE:FIRST-LAST ] [ -i ATTR ]
       [ -S SOURCE ] [ -T TYPE ] object
[…]
DESCRIPTION
       whois searches for an object in a RFC 3912 database.
[…]
OPTIONS
       -h HOST Connect to HOST.

Das gleiche unter FreeBSD:

NAME
     whois -- Internet domain name and network number directory service

SYNOPSIS
     whois [-aAbdfgiIklmQrR] [-c country-code | -h host] [-p port] name ...

DESCRIPTION
     The whois utility looks up records in the databases maintained by several
     Network Information Centers (NICs).

     The options are as follows:

[…]
     -h host
	     Use the specified host instead of the default variant.  Either a
	     host name or an IP address may be specified.

	     By default whois constructs the name of a whois server to use
	     from the top-level domain (TLD) of the supplied (single) argu-
	     ment, and appending ".whois-servers.net".	This effectively
	     allows a suitable whois server to be selected automatically for a
	     large number of TLDs.

	     In the event that an IP address is specified, the whois server
	     will default to the American Registry for Internet Numbers
	     (ARIN).  If a query to ARIN references APNIC, AfriNIC, LACNIC, or
	     RIPE, that server will be queried also, provided that the -Q
	     option is not specified.

	     If the query is not a domain name or IP address, whois will fall
	     back to whois.crsnic.net.