Hilfe und Schnittstellendoku: Wer liest was?

Auf der Roadmap stand der Punkt als „Wiki / Hilfe / API Dokumentation“. Ein Wiki ist es am Ende bewusst nicht geworden: Die Hilfeseiten liegen als Text im Quellcode und kommen mit jeder Version mit. Eine Dokumentation, die man in der Datenbank ändert, läuft unweigerlich von der Anwendung weg; ändert sich etwas, gehören die Änderung und ihre Beschreibung zusammen. Hier geht es um die anderen Fragen, die beim Bauen auftauchten: Wer darf welchen Teil lesen, wie findet man etwas darin, und wie beschreibt man eine Schnittstelle, ohne dass die Beschreibung veraltet?

Zwei Teile, zwei Leserkreise

Die Bedienungsanleitung ist für jeden, der angemeldet ist. Die technische Dokumentation ist für Administratoren. Sie beschreibt Aufbau, Datenmodell, Rechte, Betrieb, Einrichtung und die HTTP-Schnittstelle, also genau das, was jemand wissen muss, der die Installation betreibt.

Ich hätte dafür eine eigene Berechtigung „technische Dokumentation lesen“ einführen können. Das hätte aber etwas versprochen, was der Text nicht hält. Wer den Betrieb verstehen muss, betreibt die Anlage, und wer sie betreibt, ist in GODAV Pro Administrator. Deshalb hängt die Grenze fest an dieser Rolle.

Ein paar Folgen davon, die man nicht sieht, die mir aber wichtig waren:

• Wer eine technische Seite aufruft, ohne sie lesen zu dürfen, bekommt „nicht gefunden“ und nicht „verboten“. „Verboten“ würde verraten, dass es die Seite gibt.
• Verwandte Themen am Fuß einer Seite werden gefiltert. Niemand bekommt einen Verweis angeboten, der ins Leere führt.
• Aus der Bedienungsanleitung führt kein Verweis in die technische Dokumentation, umgekehrt schon. Ein Link mitten im Satz lässt sich nicht ausblenden. Er stünde für jeden blau da und endete auf einer Fehlerseite. Ein Test prüft das über alle Texte in beiden Sprachen.
• Die Texte kommen vom Server, nicht mit der Anwendung. Läge die Hilfe im ausgelieferten Programmcode, hätte jeder Browser beim ersten Aufruf auch die technische Dokumentation geladen, also auch die Browser derer, die sie gar nicht lesen dürfen.

Suchen im Menü, nicht im Text

Bei rund hundert Seiten braucht die Hilfe eine Suche. Sie arbeitet anders als die globale Suche in der Kopfzeile: Sie liefert keine Ergebnisliste, sondern kürzt das Menü. Übrig bleiben die Seiten, auf denen alle eingegebenen Wörter vorkommen. Die geöffnete Seite bleibt daneben stehen.

Gesucht wird erst nach der Eingabetaste, dann bleibt nur noch übrig, was alle Begriffe enthält.

Die erste Fassung suchte schon beim Tippen, mit einer kurzen Verzögerung. Auf dem Papier klang das gut, in der Hand war es furchtbar. Jede kleine Pause zwischen zwei Buchstaben löste eine Anfrage aus, das Menü baute sich neu auf, das Suchfeld verschwand dabei kurz, und der nächste Buchstabe ging ins Leere. Jetzt wird erst gesucht, wenn du die Eingabetaste drückst, und während der Antwort bleibt das alte Menü stehen.

Eine zweite Feinheit: Gesucht wird in der Sprachfassung, die du tatsächlich angezeigt bekommst. Sonst stünde eine Seite als Treffer im deutschen Menü, weil das Wort nur im englischen Text vorkommt.

Die Schnittstelle beschreibt sich selbst

Zur technischen Dokumentation gehört ein eigener Bereich über die HTTP-Schnittstelle, über die andere Programme mit GODAV Pro sprechen. Er erklärt die Regeln, die für jeden Aufruf gelten: wie Anmeldung und Sprache übermittelt werden, wie Antworten und Fehler aussehen, wie geblättert und gefiltert wird.

Die Regeln, die für jeden Aufruf gelten, zum Beispiel: Die Version steht in der Adresse, nicht versteckt in einem Kopf.

Die vollständige Liste aller Endpunkte mit ihren Feldern schreibe ich dagegen nicht von Hand. Sie entsteht als OpenAPI-Beschreibung automatisch aus dem Code, also aus denselben Klassen, die auch die Eingaben prüfen. Eine getrennt gepflegte Beschreibung wäre eine zweite Wahrheit, und die zweite Wahrheit verliert immer: Sie veraltet leise, weil nichts kaputtgeht, wenn jemand sie vergisst.

Die OpenAPI-Beschreibung sagt aber nur, wie ein Aufruf aussieht. Wann er zulässig ist, etwa dass ein Löschen alle Vorgänge darunter mitprüft, steht in keinem Schema. Dafür sind die Hilfeseiten da.

Bildschirmfotos aus dem Skript

Die Bilder in der Hilfe nimmt ein Skript auf, in Deutsch und Englisch, ohne Browserrahmen und ohne Entwicklerwerkzeuge. Ein von Hand gemachtes Bild wäre nach dem nächsten Umbau falsch, und niemand würde es merken. Dazu gibt es einen Prüfmodus, der alles neu aufnimmt und mit dem letzten Stand vergleicht. Verglichen wird der sichtbare Text, nicht das Bild, denn echte Daten und Uhrzeiten ändern sich ständig. Eine umbenannte Schaltfläche oder eine neue Spalte fällt so auf. Ein anderes Datum dagegen nicht.

Außerdem

• Fehlt beim Start eine Seite in einer der beiden Sprachen, oder zeigt ein Verweis auf ein Thema, das es nicht gibt, startet der Server nicht. Lieber ein lauter Fehler als eine halb übersetzte Hilfe, die unbemerkt in Betrieb geht.
• Der Knopf mit dem Fragezeichen erscheint nur, wenn es für dich auch etwas zu lesen gibt.