WP fail2ban ist ein Plugin zum Schutz von WordPress-Installationen vor Brute-Force-Angriffen. Installation und Konfiguration habe ich bereits im Artikel WordPress mit Fail2Ban vor Brute-Force-Angriffen schützen dokumentiert. Dieser Text beschäftigt sich mit der offiziellen Dokumentation des Plugins, bzw. dem Text, der sich als Dokumentation ausgibt.

Ich stelle hier meine Erwartung an eine Dokumentation heraus, zeige die Schwächen der exemplarisch ausgewählten Dokumentation heraus und gebe einen Tipp, wie man weniger schlechte Dokus schreibt. Ich schließe mit Fragen an meine Leserinnen und Leser und freue mich auf eure Rückmeldungen.

In meinen Augen sind folgende drei Abschnitte zwingender Bestandteil einer jeden Dokumentation:

1. Was ist dies für eine Anwendung? Wofür wird sie verwendet und wofür nicht?
2. Wie wird diese Anwendung installiert?
3. Wie wird diese Anwendung konfiguriert?

Die ersten beiden Punkte mag ich als erfüllt betrachten. Beim dritten Punkt sehe ich ein Problem.

Die Installationsanleitung ist prägnant. Sie enthält einen Link, der suggeriert, zur Konfigurationsanleitung zu führen. Dort erwartet den neugierigen Leser folgendes Bild.

Hier gibt es noch keine nützlichen Informationen zu sehen. Die Seite ist in meinen Augen überflüssig. Aber gut, ein Satz tut nicht weh. Mit einem Klick auf „Next“ geht es weiter.

Hier steht im Wesentlichen, dass Nutzer, welche sich bereits auskennen, zum nächsten Abschnitt gehen können. Leider finden sich für neue Nutzer hier kaum brauchbare Informationen. Der Hinweis, die Datei wp-config.php zu sichern, bevor man diese bearbeitet, ist nett, mehr nicht. Es wird erwähnt, dass die freie (im Sinne von Freibier) Version des Plugins durch Definition von Konstanten in der Datei wp-config.php konfiguriert wird. Wie so eine Konstante aussieht oder wo man weiterführende Informationen dazu findet, steht hier nicht. Ich habe an dieser Stelle entsprechende Hinweise erwartet. Gut, ich kann ja noch auf „Next“ klicken.

Auch in diesem Abschnitt findet sich keine Information, was man nun mit der Datei wp-config.php soll. Immerhin gibt es in Abschnitt 4.2.1. einen Link, der Nutzer, welche nicht mit der Konfiguration vertraut sind, zur Konfigurationsanleitung führen soll. Ich habe ein Déja Vu und fühle mich langsam ver…hohnepiepelt. Also klicke ich auf den nächsten LInk. Es heißt ja schließlich: „Was lange währt, wird endlich gut.“

TL;DR: Auch auf der nächsten Seite erfahren wir nichts über die wp-config.php.

Zur Erinnerung: Ich nutze die freie Version des Plugins WP fail2ban, welches angeblich durch die Definition von Konstanten in der Datei wp-config.php konfiguriert wird. Welche Konstanten dies sind und wie man diese konfiguriert, wird auch auf Seite 4 immer noch nicht mit einem Wort erklärt.

Stattdessen lernt man in Abschnitt „4.3.1.1. Typical Settings“, dass die Dateien wordpress-hard.conf und wordpress-soft.conf in das Verzeichnis fail2ban/filters.d zu kopieren sind. Hier wurden in meinen Augen zwei Fehler gemacht:

1. Es wird nicht erwähnt, wie man die Dateien wordpress-,{hard,soft}.conf erhält bzw. erstellt. Als unerfahrener Nutzer strandet man hier. Zum Glück hatte ich mir das damals aufgeschrieben.
2. Es wird eine relative Pfadangabe fail2ban/filters.d genutzt. Dies ist nicht ganz so wild, ich persönlich bevorzuge es, wenn vollständige Pfadangaben genutzt werden, damit Nutzer das entsprechende Verzeichnis sicher finden.

Fazit

Eine Dokumentation sollte die notwendigen Informationen bereitstellen, mit denen auch neue Nutzer eine Anwendung installieren und konfigurieren können. Dies ist nicht so leicht, wie es auf den ersten Blick erscheint, leiden Autoren, welche die Anwendung bereits kennen, doch häufig unter Betriebsblindheit und können sich nur schwer in die Rolle des unerfahrenen Nutzers versetzen.

Wenn ich selbst Dokumentationen schreibe, gebe ich diese meist Kolleginnen und Kollegen zu lesen und arbeite deren Rückmeldungen mit ein. Dies hat in der Vergangenheit zu deutlich besseren Ergebnissen geführt.

Die hier kritisierte Dokumentation ist ein Beispiel dafür. Sie befindet sich damit leider in guter Gesellschaft im Internet.

Ohne meinen Eingangs erwähnten Artikel hier im Blog wäre ich nicht in der Lage gewesen, mir dieses Plugin wieder einzurichten. Nun werde ich einige Tage prüfen, ob es wie erhofft arbeitet und dann ggf. einen Merge-Request mit einigen Verbesserungsvorschlägen einreichen.

Fragen an meine Leserinnen und Leser

Wie steht ihr zu Dokumentation? Ist das eher etwas für alte weiße Männer mit grauen Bärten? Oder wünscht ihr euch ebenfalls belastbare und ausführliche Dokumentationen zu den von euch verwendeten Anwendungen?

Tragt ihr selbst zu Dokumentationen bei? Welche Erfahrungen habt ihr dabei gemacht? Welche Tipps könnt ihr Schreiberlingen geben, die ihr Projekt dokumentieren möchten?

Bitte hinterlasst mir eure Antworten in den Kommentaren oder im Chat.