Wie wir dokumentieren

Eine Doku hilft nur, wenn du dich auf sie verlassen kannst. Das sind die Regeln, nach denen das up4-Team schreibt, und die Prüfungen, die uns daran halten.

Zwei Bereiche, zwei Arten von Lesern

Das Handbuch ist für alle, die mit der App arbeiten. Jede Seite beginnt mit einer Aufgabe, etwa Website überwachen, benutzt die Wörter, die du auf dem Bildschirm siehst, und endet mit dem, was du siehst, wenn es geklappt hat.

Die Entwicklerdoku (Englisch) ist für Menschen und Programme, die die API aufrufen. Sie beginnt mit dem Vertrag: Anmeldung, Aufbau von Anfrage und Antwort, Fehler. Die beiden Bereiche treffen sich nur im eingeklappten Kasten „Per API“ am Ende einer Aufgabenseite.

Fakten kommen aus dem Produkt

Was das Produkt schon weiß, tippen wir nicht ab:

• Beschriftungen. Jeder Name einer Schaltfläche, eines Felds oder Menüs im Handbuch wird beim Erstellen der Doku aus den Texten der App gelesen, auf Deutsch und auf Englisch. Ändert sich eine Beschriftung in der App, ändert sich die Seite mit. Verschwindet sie, schlägt das Erstellen der Doku fehl.
• Preise. Kostenbeispiele werden mit derselben Formel berechnet wie die Schätzung in der App, nicht von Hand geschrieben.
• Zeiten. Werte wie die Zahl der Ergebnisse, die einen Ausfall bestätigen, kommen aus dem Code, der die Entscheidung trifft. Ein Test hält beide gleich. Der Zeitstrahl auf Wann du benachrichtigt wirst rechnet mit genau diesen Werten.

Wo das Produkt keine feste Zahl hat, etwa wie lange eine E-Mail unterwegs ist, erklären wir, wovon es abhängt, statt etwas zu versprechen.

Jede Aufgabe wird durchgespielt

Zu jeder Aufgabenseite gehört ein Skript, das Schritt für Schritt tut, was die Seite beschreibt, in einer echten, laufenden up4-Installation mit einem Beispielunternehmen. Es benutzt die Beschriftungen, die die Seite nennt, und nimmt die Bilder auf, die du siehst, einmal auf Deutsch und einmal auf Englisch.

Vor jeder Veröffentlichung wird geprüft, ob diese Durchläufe für die aktuellen Seiten und App-Texte gelaufen sind. Hat sich seit dem letzten erfolgreichen Durchlauf eine Seite oder die App geändert, wird nichts veröffentlicht, bis die Durchläufe wieder bestehen. So kann keine Seite still einen Bildschirm beschreiben, den es nicht mehr gibt.

Die API-Referenz kommt aus dem Code

• Die Schemas für Anfragen und Antworten entstehen aus den Typen, die jede Route wirklich verwendet. Eine öffentliche Route ohne erklärten Typ lässt den Build scheitern.
• Die Beispielantworten stammen aus Testläufen gegen die API und sind anonymisiert, nicht von Hand geschrieben.
• Das Änderungsprotokoll der API entsteht aus dem Unterschied zwischen zwei Fassungen der Spezifikation.

Wie wir schreiben

• Überschriften nennen die Aufgabe. Schritte sind nummeriert, höchstens sieben am Stück.
• Kurze Sätze, einfache Sprache, keine Werbewörter.
• Jede Aufgabenseite sagt, was up4 an dieser Stelle nicht kann. Eine Grenze, die du aus der Doku kennst, ist besser als eine, die du im Betrieb entdeckst.
• Das Handbuch entsteht auf Deutsch und auf Englisch jeweils für sich, nicht Satz für Satz übersetzt. Die deutschen Seiten duzen dich und verzichten auf Gender-Formen.
• Seiten zum Umzug von einem anderen Werkzeug vergleichen nur, was wir in dessen aktuellem Produkt oder dessen öffentlicher Doku geprüft haben.

Für Werkzeuge und Agenten

Jede Seite gibt es auch als Markdown: Häng .md an ihre Adresse oder nimm „Seite kopieren“ oben auf der Seite. llms.txt listet die Seiten für Sprachmodelle auf, getrennt nach Handbuch und Entwicklerdoku.

Sag uns, wenn eine Seite nicht stimmt

Am Ende jeder Seite fragen wir, ob sie geholfen hat. Wir zählen Ja und Nein je Seite, ohne Cookies. Bei Nein kannst du einen Satz dazu schreiben, was gefehlt hat. Der geht an das up4-Team. Eine Seite, die viele Nein sammelt, schreiben wir neu.