N
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.
