Seminar Antora – Suche mit Lunr und Informationszugang

Beschreibung

Das Seminar vermittelt Konzeption, Integration und Qualitätssicherung einer clientseitigen Lunr-Suche für Antora-Sites. Indexumfang, Sprachverarbeitung, Metadaten, Ausschlüsse, UI, Relevanz, Performance, Barrierefreiheit und automatisierte Suchtests werden anhand einer mehrkomponentigen Dokumentationssite umgesetzt. Die Suchfunktion wird als Teil der Informationsarchitektur und nicht nur als technisches Zusatzmodul behandelt.

Inhaltsübersicht

1. Suchziele und Indexmodell
2. Installation und Indexerstellung
3. Sprachen, Tokenisierung und Fachbegriffe
4. Suchoberfläche und UI-Integration
5. Relevanz und Suchqualität
6. Performance, Regression und Betrieb

Lernziele

• Indexumfang und Metadaten nach fachlichen Suchzielen festlegen.
• Lunr-Suche mit geeigneter Sprachverarbeitung in Antora integrieren.
• Suchoberfläche, Relevanz und Performance methodisch prüfen.
• Regressionstests und Betriebskennzahlen für die Suche etablieren.

1. Suchziele und Indexmodell

Eine gute Suche beginnt mit dokumentierten Nutzerfragen und einem kontrollierten Indexumfang.

Schritt-für-Schritt: Ein fachliches Suchmodell definieren

1. Zielgruppen und typische Informationsfragen als Suchszenarien erfassen.
2. Zu indexierende Komponenten, Versionen, Seitentypen und Metadaten bestimmen.
3. Ausschlüsse für veraltete, doppelte, technische oder nicht öffentliche Inhalte festlegen.
4. Felder wie Titel, Text, Breadcrumb, Komponente und Version nach Suchnutzen priorisieren.
5. Erwartete Treffer und Nichttreffer für repräsentative Abfragen dokumentieren.
6. Das Modell mit Content Ownern und Informationsarchitektur abstimmen.

Praxisaufgabe

Ein Suchanforderungskatalog mit Indexfeldern, Ausschlüssen und erwarteten Ergebnissen wird erstellt.

2. Installation und Indexerstellung

Die Sucherweiterung wird reproduzierbar in den Antora-Build eingebunden.

Schritt-für-Schritt: Einen ersten Lunr-Index erzeugen

1. Benötigte Suchpakete projektbezogen installieren und Versionen sperren.
2. Erweiterung im Playbook am vorgesehenen Lebenszykluspunkt registrieren.
3. Indexausgabe und zugehörige UI-Assets eindeutig konfigurieren.
4. Einen Build mit mehreren Komponenten und Versionen ausführen.
5. Erzeugte Indexdatei auf Größe, Struktur und enthaltene Dokumente prüfen.
6. Fehlende oder unerwartete Seiten auf Konfigurations- und Metadatenursachen zurückführen.

Praxisaufgabe

Eine mehrkomponentige Site erhält einen reproduzierbaren, technisch geprüften Suchindex.

3. Sprachen, Tokenisierung und Fachbegriffe

Sprachverarbeitung und Fachterminologie beeinflussen Trefferqualität unmittelbar.

Schritt-für-Schritt: Eine sprachgerechte Suchkonfiguration erstellen

1. Dokumentationssprachen und sprachgemischte Inhaltsbereiche erfassen.
2. Geeignete Tokenisierung, Kleinschreibung, Stoppwörter und Wortstammverarbeitung auswählen.
3. Fachbegriffe, Abkürzungen, Produktnamen und Schreibvarianten in einen Testkatalog aufnehmen.
4. Sprachspezifische Konfigurationen getrennt bauen und vergleichen.
5. Fehlende Treffer durch Inhalts-, Index- oder Sprachursache unterscheiden.
6. Regeln für Synonyme oder redaktionelle Terminologieergänzungen dokumentieren.

Praxisaufgabe

Deutsche und englische Fachabfragen werden verglichen und die Verarbeitung für kritische Begriffe angepasst.

4. Suchoberfläche und UI-Integration

Suche muss in Navigation und Seitenlayout verständlich, zugänglich und fehlertolerant eingebettet sein.

Schritt-für-Schritt: Eine nutzbare Suchoberfläche implementieren

1. Suchfeld, Auslöser, Ergebnisbereich und Zustandsmeldungen im UI-Modell verorten.
2. UI-Templates und JavaScript für Laden, Abfrage und Ergebnisdarstellung anbinden.
3. Treffer mit Titel, Kontext, Komponente und Version verständlich darstellen.
4. Leere Abfragen, keine Treffer, Ladefehler und große Ergebnismengen behandeln.
5. Tastaturbedienung, Fokusführung, Beschriftungen und Statusausgaben prüfen.
6. Darstellung auf kleinen und großen Ansichten testen.

Praxisaufgabe

Eine barrierearm bedienbare Suchoberfläche wird in das Seminar-UI integriert.

5. Relevanz und Suchqualität

Relevanz wird mit einem stabilen Testkatalog statt mit Einzelbeobachtungen bewertet.

Schritt-für-Schritt: Trefferqualität messen und verbessern

1. Abfragen mit eindeutigem, mehrdeutigem und fehlendem Ziel zusammenstellen.
2. Erwartete Top-Treffer und tolerierbare Alternativen je Abfrage festlegen.
3. Aktuelle Rangfolge protokollieren und Abweichungen klassifizieren.
4. Gewichtung von Titel, Text und Metadaten kontrolliert anpassen.
5. Doppelte oder veraltete Treffer durch Indexregeln oder Inhaltsbereinigung reduzieren.
6. Nach jeder Änderung den vollständigen Testkatalog erneut ausführen.

Praxisaufgabe

Ein Relevanzbericht mit Vorher-Nachher-Vergleich für mindestens zwanzig Suchabfragen wird erstellt.

6. Performance, Regression und Betrieb

Indexgröße und Browserausführung müssen auch bei wachsenden Dokumentationsbeständen beherrschbar bleiben.

Schritt-für-Schritt: Suche für den Regelbetrieb absichern

1. Indexgröße, Build-Zeit, Ladezeit und Abfragezeit als Baseline messen.
2. Inhaltsumfang und Metadaten auf unnötige Indexlast prüfen.
3. Grenzwerte für Warnung und Fehler in der Build-Pipeline definieren.
4. Automatisierte Tests für erwartete Treffer und ausgeschlossene Inhalte einrichten.
5. Indexartefakt, Konfiguration und Suchtestbericht versioniert aufbewahren.
6. Eigentum, Aktualisierung und Fehlerbehandlung in ein Betriebsrunbook aufnehmen.

Praxisaufgabe

Ein wachsender Testbestand wird gemessen, optimiert und durch automatisierte Suchregressionen abgesichert.

Zielgruppe und Voraussetzungen

Zielgruppe: Documentation Engineers, technische Redakteure, Informationsarchitektur, UI- und Webentwicklung, Plattformbetrieb und Qualitätsmanagement.

Voraussetzungen: Grundkenntnisse in Antora, Navigation und UI-Bundles; JavaScript- und Suchgrundlagen sind hilfreich.

Methodik und Arbeitsweise

Die Inhalte werden durch strukturierte Erläuterungen, Demonstrationen, schrittweise Konfigurations- und Analyseaufgaben sowie kontrollierte Fehlerfälle vertieft. Jede Übung verwendet definierte Ausgangswerte, Prüfpunkte und Dokumentationsanforderungen, damit die erarbeiteten Abläufe im späteren Projekt- und Betriebsalltag reproduzierbar bleiben.