254 lines
11 KiB
Markdown
254 lines
11 KiB
Markdown
Die Weboberfläche ist der Zugang für Menschen. Sie zeigt dasselbe Wissen, das
|
|
auch die Agenten sehen.
|
|
|
|
## Anmelden
|
|
|
|
Angemeldet wird mit dem API-Key des Projekts, also demselben, den auch das
|
|
KI-Werkzeug benutzt. Einen Benutzernamen gibt es nicht: Der Key bestimmt, wer
|
|
du bist, in welchem Projekt du arbeitest und was du darfst. Wird der Key
|
|
zurückgezogen, endet auch die Sitzung im Browser sofort.
|
|
|
|
## Finden
|
|
|
|
- **Suchen:** Das Suchfeld über der Eintragsliste durchsucht Titel,
|
|
Schlagworte und Inhalt. Titel zählen am stärksten. Umlaute sind egal:
|
|
„Uberblick“ findet auch „Überblick“. Ein Wortanfang reicht, „deploy“ findet
|
|
auch „Deployment“. Ebenso findet „prozess“ den „Releaseprozess“ und
|
|
„zertifikate“ das „Zertifikat“. Kleine Tippfehler gleicht die Suche aus,
|
|
wenn sonst nichts passt: „deploymnet“ findet „Deployment“. Genaue Treffer
|
|
stehen immer vor ungefähren.
|
|
- **Nach Schlagwort filtern:** In der Seitenleiste stehen die zehn häufigsten
|
|
Schlagworte des Projekts. Ein Klick filtert die Liste. Gibt es mehr, führt
|
|
*Alle Schlagworte…* zu einer Seite mit der vollständigen Liste, nach
|
|
Häufigkeit oder alphabetisch sortiert und mit einem Filterfeld.
|
|
- **Verweisen folgen:** Unter jedem Eintrag steht, welche anderen Einträge auf
|
|
ihn verweisen, und unter *Auch verwandt* die Einträge, die über einen
|
|
Zwischeneintrag mit ihm verknüpft sind (siehe [unten](#verwandte-eintraege)).
|
|
- **Veraltete Einträge:** Einträge, die seit über einem Jahr niemand geändert
|
|
hat, tragen die Marke *veraltet*. Neben dem Suchfeld steht dann ein Link wie
|
|
*3 veraltet*, der die Liste auf genau diese Einträge filtert. Die Zahl steht
|
|
auch auf der Nutzungsseite. Ein veralteter Eintrag kann noch stimmen, sollte
|
|
aber geprüft werden: Stimmt er noch, einmal speichern (oder kuratieren), dann
|
|
zählt er wieder als aktuell; sonst korrigieren oder löschen.
|
|
- **Tastenkürzel:** `/` springt ins Suchfeld, `n` legt einen neuen Eintrag an,
|
|
`e` bearbeitet den angezeigten Eintrag, `Strg+Enter` (Mac: `Cmd+Enter`)
|
|
speichert im Formular. Die Buchstaben gelten nur, wenn gerade kein
|
|
Eingabefeld aktiv ist, und nur, wo die Rolle das darf.
|
|
- **Graph:** Unter *Graph* in der Seitenleiste zeigt Munin, wie die Einträge
|
|
über Verweise zusammenhängen. Gestrichelte Knoten sind Verweisziele, zu denen
|
|
es noch keinen Eintrag gibt. Mausrad zoomt, Ziehen verschiebt, ein Klick
|
|
öffnet den Eintrag. Beschriftet sind zunächst nur die wichtigsten Knoten;
|
|
beim Hineinzoomen rücken die Knoten auseinander und weitere Namen
|
|
erscheinen. Zeigt die Maus auf einen Knoten, treten er und seine direkten
|
|
Nachbarn hervor. Bei sehr großen Projekten zeigt der Graph nur die 150 am
|
|
stärksten verknüpften Einträge.
|
|
|
|
## Schreiben
|
|
|
|
Mit der Rolle `write` oder `admin` gibt es über der Liste den Knopf
|
|
**Neuer Eintrag** und in jedem Eintrag **Bearbeiten**.
|
|
|
|
| Feld | Bedeutung |
|
|
|---|---|
|
|
| Titel | Worum es geht, am besten als Frage oder klares Thema |
|
|
| Bezeichner | Der dauerhafte Name, siehe [Begriffe](/hilfe/begriffe). Leer lassen, dann wird er aus dem Titel abgeleitet. |
|
|
| Schlagworte | Durch Komma getrennt. Möglichst vorhandene wiederverwenden. |
|
|
| Inhalt | Markdown (siehe unten) |
|
|
| Kuratiert | Haken setzen, wenn der Inhalt geprüft und verlässlich ist |
|
|
|
|
**Bevor du einen neuen Eintrag anlegst**, such kurz, ob es das Thema schon gibt.
|
|
Ergänzen ist fast immer besser als ein zweiter Eintrag.
|
|
|
|
### Gibt es schon?
|
|
|
|
Beim Tippen des Titels eines neuen Eintrags zeigt Munin darunter vorhandene
|
|
Einträge mit ähnlichem Titel, samt der Wörter, die sie gemeinsam haben. Das
|
|
ist dieselbe Prüfung, mit der Munin bei Agenten nachfragt, bevor sie einen
|
|
zweiten Eintrag zum selben Thema anlegen. Hier ist es nur ein Hinweis:
|
|
Passt einer, öffne ihn (der Link geht in einem neuen Tab auf) und schreib dort
|
|
weiter. Ist es ein anderes Thema, einfach speichern.
|
|
|
|
### Ungespeicherte Änderungen
|
|
|
|
Wer im Formular etwas geändert hat und die Seite verlässt, ohne zu speichern,
|
|
etwa durch einen Klick in der Seitenleiste, bekommt eine Rückfrage des
|
|
Browsers. Den Wortlaut legt der Browser fest.
|
|
|
|
### Markdown im Inhalt
|
|
|
|
Unterstützt werden die üblichen Auszeichnungen:
|
|
|
|
```markdown
|
|
## Zwischenüberschrift
|
|
|
|
Normaler Text mit **fett**, *kursiv* und `Code`.
|
|
|
|
- Aufzählung
|
|
- noch ein Punkt
|
|
|
|
1. Nummerierte Schritte
|
|
2. zweiter Schritt
|
|
|
|
[Ein Link](https://example.org)
|
|
|
|
Siehe auch [[anderer-eintrag]].
|
|
```
|
|
|
|
Dazu kommen die Erweiterungen, die man von GitHub oder GitLab kennt:
|
|
|
|
```markdown
|
|
| Umgebung | Adresse |
|
|
|----------|----------------|
|
|
| Test | test.intern |
|
|
| Prod | prod.intern |
|
|
|
|
- [x] erledigt
|
|
- [ ] noch offen
|
|
|
|
~~veraltet~~ — durchgestrichen
|
|
|
|
https://example.org wird ohne Klammern zum Link.
|
|
```
|
|
|
|
Codeblöcke stehen zwischen drei Backticks. Eingebettetes HTML wird aus
|
|
Sicherheitsgründen nicht ausgeführt.
|
|
|
|
### Verweise mit Autovervollständigung
|
|
|
|
Tippe `[[` in das Inhaltsfeld. Munin schlägt passende Einträge vor. Mit den
|
|
Pfeiltasten auswählen und mit Enter oder Tab übernehmen, oder einfach anklicken.
|
|
Eingefügt wird der Bezeichner, nicht der Titel.
|
|
|
|
### Vorschau
|
|
|
|
Über dem Inhaltsfeld wechselst du zwischen **Schreiben** und **Vorschau**. Die
|
|
Vorschau zeigt den Eintrag genau so, wie er nach dem Speichern aussehen wird.
|
|
|
|
### Wenn jemand gleichzeitig ändert
|
|
|
|
Hat jemand anderes (ein Mensch oder ein Agent) den Eintrag geändert, während du
|
|
ihn bearbeitet hast, meldet Munin beim Speichern einen Konflikt, statt die
|
|
fremde Änderung zu überschreiben. Dein Text bleibt im Formular erhalten. Öffne
|
|
den Eintrag in einem zweiten Tab, übernimm dort deine Änderungen in den
|
|
aktuellen Stand und speichere dann dort.
|
|
|
|
## Verwandte Einträge
|
|
|
|
Unter einem Eintrag stehen zwei Listen:
|
|
|
|
- **Verweist hierher:** Einträge, die mit `[[…]]` direkt auf diesen verweisen.
|
|
- **Auch verwandt:** Einträge, die über einen **Zwischeneintrag** verknüpft
|
|
sind, mit dem Hinweis *über …*. Verweist „Deployment“ auf „Pipeline“ und
|
|
„Pipeline“ auf „Runner“, steht unter „Deployment“: *Runner, über pipeline*.
|
|
|
|
So findet man Zusammenhänge, die kein Suchwort gemeinsam haben, aber von
|
|
jemandem bewusst verknüpft wurden. Agenten bekommen dasselbe über das Werkzeug
|
|
`related`.
|
|
|
|
## Verlauf und Vergleich
|
|
|
|
In jedem Eintrag führt **Fassung n, Verlauf ansehen** zu allen früheren
|
|
Fassungen. Bei jeder Fassung zeigt **Änderungen ansehen** Zeile für Zeile, was
|
|
sich zur nächsten Fassung geändert hat. So lässt sich nachvollziehen, was ein
|
|
Agent geändert hat.
|
|
|
|
Mit Schreibrecht holt **Wiederherstellen** (im Verlauf oder auf der
|
|
Vergleichsseite) eine alte Fassung mit einem Klick zurück: Titel, Inhalt und
|
|
Schlagworte. Dabei geht nichts verloren — der bisherige Stand wird selbst zu
|
|
einer Fassung im Verlauf, und das Protokoll vermerkt, welche Fassung
|
|
zurückgeholt wurde. Hat jemand den Eintrag geändert, während du den Verlauf
|
|
angesehen hast, wird nichts überschrieben; prüfe dann den neuen Stand und
|
|
versuche es erneut.
|
|
|
|
Der Haken **Kuratiert** bleibt beim Wiederherstellen so, wie er gerade ist. Hat
|
|
ein Agent einen geprüften Eintrag geändert (dabei fällt der Haken weg) und
|
|
holst du den geprüften Stand zurück, setze den Haken danach wieder.
|
|
|
|
## Papierkorb
|
|
|
|
**Löschen** legt einen Eintrag in den Papierkorb, egal ob ein Mensch in der
|
|
Oberfläche löscht oder ein Agent über `forget`. Der Eintrag verschwindet sofort
|
|
aus Liste, Suche, Graph und allen Antworten an Agenten. Mit Verlauf und
|
|
Schlagworten bleibt er aber 30 Tage erhalten; danach entfernt Munin ihn
|
|
endgültig.
|
|
|
|
Den Papierkorb findest du mit Schreibrecht in der Seitenleiste. Dort steht zu
|
|
jedem Eintrag, wer ihn wann gelöscht hat:
|
|
|
|
- **Wiederherstellen** holt einen Eintrag unverändert zurück.
|
|
- **Endgültig löschen** entfernt ihn sofort, samt Verlauf. Das ist gedacht für
|
|
Inhalte, die nicht 30 Tage liegen bleiben sollen, etwa ein versehentlich
|
|
abgelegtes Passwort. Rückgängig machen lässt sich das nicht.
|
|
- Ein Klick auf den **Namen eines Zugangs** zeigt nur, was dieser gelöscht hat.
|
|
Hat ein Agent zu gründlich aufgeräumt, holt *Alle … wiederherstellen* alles
|
|
auf einmal zurück.
|
|
|
|
Wer mit Leserecht angemeldet ist, sieht den Papierkorb nicht. Oft wird ein
|
|
Eintrag ja gerade deshalb gelöscht, weil nicht jeder ihn sehen soll.
|
|
|
|
Legst du einen Eintrag mit einem Bezeichner an, der noch im Papierkorb liegt,
|
|
holt Munin den alten Eintrag zurück und überschreibt ihn. Der gelöschte Stand
|
|
steht dann im Verlauf, und ein Hinweis sagt dir, dass das passiert ist.
|
|
|
|
Veraltetes trotzdem lieber überarbeiten als löschen: Überarbeitetes bleibt
|
|
auffindbar, und der Verlauf zeigt, was sich geändert hat.
|
|
|
|
## Viele Einträge auf einmal
|
|
|
|
Mit Schreibrecht hat die Eintragsliste vor jedem Eintrag ein Auswahlkästchen.
|
|
Unter der Liste gibt es für alle ausgewählten Einträge zwei Aktionen:
|
|
|
|
- **Schlagworte ändern:** hinzufügen oder entfernen, mehrere durch Komma
|
|
getrennt, dann *Anwenden*. Praktisch, um ein Schlagwort umzubenennen: das
|
|
neue hinzufügen, das alte entfernen.
|
|
- **In den Papierkorb:** legt alle ausgewählten Einträge nach einer Rückfrage
|
|
in den Papierkorb, wie das Löschen eines einzelnen Eintrags. Danach stehst
|
|
du wieder in derselben Liste, mit derselben Suche oder demselben Filter. War
|
|
es zu viel, holt der Papierkorb alles mit *Alle … wiederherstellen* in einem
|
|
Zug zurück.
|
|
|
|
## Import
|
|
|
|
Mit der Rolle `admin` gibt es in der Seitenleiste den Punkt *Import*. Dort
|
|
lässt sich ein ZIP-Archiv mit Markdown-Dateien hochladen. Jede Datei wird ein
|
|
Eintrag. Das passt für drei Fälle:
|
|
|
|
- **Wiederherstellen** aus dem Markdown-Export: das ZIP aus *Als ZIP herunterladen*
|
|
direkt hochladen, oder den Ordner eines Projekts aus dem Exportverzeichnis
|
|
des Servers packen und hochladen. Schlagworte, Autor, Herkunft, Prüfvermerk und
|
|
Änderungsdatum bleiben erhalten.
|
|
- **Umzug** eines Projekts auf einen anderen Server oder in einen anderen
|
|
Workspace, auf demselben Weg.
|
|
- **Vorhandene Dokumentation** übernehmen. Der Bezeichner kommt aus dem
|
|
Dateinamen, der Titel aus der ersten Überschrift `# …`. Unterordner sind
|
|
erlaubt, im Projekt stehen die Einträge danach aber nebeneinander.
|
|
|
|
Gibt es einen Bezeichner schon, wird die Datei entweder **übersprungen**
|
|
(Standard) oder sie **überschreibt** den Eintrag. Beim Überschreiben wandert
|
|
der bisherige Stand in den Verlauf, verloren geht also nichts. Dateien, die
|
|
nichts ändern würden, werden in beiden Fällen nicht geschrieben. Derselbe
|
|
Import lässt sich deshalb gefahrlos wiederholen.
|
|
|
|
**Nur Vorschau** ist beim ersten Hochladen angehakt. Die Tabelle zeigt dann
|
|
für jede Datei, was passieren würde, ohne etwas zu schreiben. Passt alles,
|
|
dasselbe Archiv ohne den Haken noch einmal hochladen.
|
|
|
|
Nicht übernommen wird der Verlauf, denn der Export enthält nur den aktuellen
|
|
Stand. Ein importierter Eintrag beginnt deshalb wieder bei Fassung 1.
|
|
|
|
## Export als ZIP
|
|
|
|
Mit der Rolle `admin` steht über der Eintragsliste der Knopf *Als ZIP
|
|
herunterladen*. Ein Klick lädt alle Einträge des Projekts als ZIP-Archiv herunter: je Eintrag
|
|
eine Markdown-Datei mit allen Feldern im Kopf, dazu eine Übersicht
|
|
`_index.md`. Der Papierkorb und der Verlauf älterer Fassungen sind nicht
|
|
enthalten.
|
|
|
|
Das Archiv passt unverändert in den [Import](#import), in dieses oder ein
|
|
anderes Projekt, auch auf einem anderen Server. Jeder Download steht im
|
|
Protokoll.
|
|
|
|
## Protokoll
|
|
|
|
Unter *Protokoll* in der Seitenleiste steht, wer im Projekt wann etwas
|
|
geschrieben, gelöscht oder sich angemeldet hat.
|