Ein Ordner in deinem Repository wird zur Doku im Projekt.
Du schreibst die Doku deiner Software dort, wo sie hingehört: als Dateien in deinem Repository, standardmäßig im Ordner .lalabase/doku/. Diesen Ordner hängst du ins Projekt ein, und Lalabase hält ihn beim Sync auf Stand. Das Repository bleibt die Quelle der Wahrheit, im Projekt steht eine lesbare Kopie. Kunden und externe Entwickler holst du als Gast ins Projekt, damit sie genau diese Doku lesen können.
- 01 Ein Ordner im Repository, im Projekt unter Dokumentation lesbar
- 02 Der Sync läuft in eine Richtung: geändert wird im Repository, nie in Lalabase
- 03 Seiten, die sich seit dem letzten Besuch geändert haben, sind markiert. So sieht dein Kunde, was neu dazugekommen ist
- 04 Mehrere Doku-Sätze je Projekt, etwa Handbuch und Änderungsverlauf getrennt
- 05 Die Doku-Seiten stehen dem Projekt-Chat als Quelle bereit. Fragt dein Kunde im Chat, kommt die Antwort aus deiner eigenen Doku
- 06 Dazu lässt sich der Quellcode einlesen. Gesucht wird dann nicht der Dateiname, sondern die Struktur des Codes
So läuft das
GitHub oder GitLab, ein Zugriffstoken, fertig. Das Projekt weiß danach, wo sein Quellcode liegt und welcher Zweig der maßgebliche ist.
Voreingestellt ist `.lalabase/doku/`. Jede Markdown-Datei darin wird zu einer Seite, die Ordnerstruktur wird zur Gliederung.
Im Editor, im Zweig, im Pull Request, mit Review. Die Doku altert nicht getrennt vom Code, weil sie neben ihm liegt und mit ihm zusammen geprüft wird.
Wer keinen Zugang zum Repository hat, liest sie trotzdem. Jede Seite trägt den Commit, aus dem sie stammt, und der Projekt-Chat beantwortet Fragen daraus mit Quellenangabe.
Was es nicht tut
Drei Grenzen, die sich aus dieser Richtung ergeben.
- Eine Einbahnstraße. Lalabase liest das Repository und schreibt nichts hinein. Geändert wird die Doku dort, wo sie liegt.
- Nur GitHub und GitLab. Ein selbst betriebener Git-Server ist heute nicht angebunden.
- Nur Markdown. Was sonst noch im Ordner liegt, bleibt liegen.
Was Leute an dieser Stelle fragen
- Was passiert, wenn jemand im Repository etwas ändert?
- Der Stand wird nachgezogen, und jede Seite weiß, aus welchem Commit sie stammt. Du siehst also nicht nur den Text, sondern auch, wie alt er ist.
- Brauchen alle im Team einen Zugang zum Repository?
- Nein, und das ist der Punkt. Der Zugang liegt einmal beim Projekt. Wer die Doku lesen soll, bekommt Leserechte im Projekt, nicht bei GitHub.
- Warum kein Wiki in der Anwendung?
- Weil die Doku dann zweimal existiert. Ein Wiki neben dem Repository ist nach einem halben Jahr die Fassung, der niemand mehr traut. Für Notizen, die nicht zum Code gehören, gibt es Notizen im Projekt.
Sieh es dir an,
statt es zu glauben.
In unter 5 Minuten produktiv. Keine Vertriebsschleife.
Besondere Datenschutz- oder Compliance-Anforderungen? Sprich uns an. Für solche Fälle finden wir in aller Regel eine Lösung.