Doku-Erfolg messen: Analytics in AsciiDoc implementieren

Sie können den Erfolg Ihrer Dokumentation präzise messen. Dafür brauchen Sie zwei Dinge:

1. Klar definierte Kennzahlen.

2. Eine saubere technische Umsetzung in Ihrem AsciiDoc-Setup.

In diesem Beitrag gehe ich Schritt für Schritt vor: Zuerst klären wir, welche Metriken für Ihre Dokumentation wirklich sinnvoll sind, etwa Seitenaufrufe, Lesezeit, Scrolltiefe, Download-Rate von PDFs oder Klicks auf bestimmte Call-to-Actions.

Danach schauen wir, was technisch gegeben sein muss, also zum Beispiel ein Web-Analytics-Tool, saubere URLs, konsistente UTM-Parameter und eine klare Struktur Ihrer AsciiDoc-Quellen.

Zum Schluss zeige ich Ihnen, wie Sie diese Metriken konkret in AsciiDoc einbauen, etwa indem Sie Tracking-Links und Ereignis-IDs direkt in den Quelltext integrieren, sodass sie in HTML-, PDF- und weiteren Web-Exports automatisch mit ausgegeben werden.

Voraussetzungen, damit Tracking überhaupt funktioniert

Bevor Sie Kennzahlen diskutieren, stellen Sie sicher:

Eindeutige URLs und IDs

• Jede Doku-Seite hat eine stabile URL.

• Jede Seite hat eine eindeutige Kennung (doc-id).

• Diese Kennung taucht im HTML, im PDF (indirekt) und in Events auf.

Zentrales Template oder Include

• Kein Tracking-Code in jedem AsciiDoc-Dokument einzeln.

• Ein gemeinsames Include oder Layout-Template, das die doc-id ausliest und Analytics- oder Logging-Code einbettet.

Analytics- oder Logging-System

Typische Optionen:

• Web-Analytics (z. B. Matomo On-Prem, Plausible, GA4).

• Eigenes Backend (Events per REST-API).

• Kombination mit Support-System (Zendesk, Freshdesk, o. Ä.) für Deflection.

Consent / Datenschutz

• Saubere Einwilligung, wenn Sie personenbezogene oder pseudonyme Nutzerdaten erfassen.

• Im Idealfall: selbst gehostete, datensparsame Lösung.

Kennzahlen-Kategorien und wie Sie sie einbinden

1. Seitenaufrufe (Page Views)

Was: Wie oft eine Seite aufgerufen wurde. Basiskennzahl für Nutzung.

Technische Voraussetzungen

• Stabile URL pro Seite.

• Tracking-Snippet im HTML-Template.

• doc-id als eindeutiger Identifier.

AsciiDoc-Beispiel

Im Kopf jeder Seite:

= Getting Started mit Product X
:doc-id: getting-started
:doc-area: onboarding
:doc-version: 1.4

Im HTML-Template oder als Include:

ifdef::backend-html5[]

++++
<script>
  (function() {
    // Attribute über Meta-Tags oder data-Attribute bereitstellen
    const docMeta = document.querySelector('meta[name="doc-id"]');
    const areaMeta = document.querySelector('meta[name="doc-area"]');
    const versionMeta = document.querySelector('meta[name="doc-version"]');
    
    const docId = docMeta ? docMeta.content : 'unknown';
    const area = areaMeta ? areaMeta.content : 'unknown';
    const version = versionMeta ? versionMeta.content : 'unknown';

    // Pageview an Ihr System senden
    // pageview({ page: window.location.pathname, docId, area, version });
  })();
</script>
++++

endif::[]

Wichtiger Hinweis: AsciiDoc substituiert Attribute innerhalb von Passthrough-Blöcken (++++...++++) standardmäßig nicht. Verwenden Sie stattdessen Meta-Tags im Dokumentkopf oder data-Attribute auf einem Container-Element, die Sie dann per JavaScript auslesen. Siehe Anhang für Details.

Wo messen?

In Ihrem Analytics unter "Seiten" / "Pages" nach page oder docId. Sie können:

• Aufrufe nach doc-area gruppieren (z. B. Onboarding, API, Admin).

• Releases vergleichen (doc-version).

• Top- und Low-Performer identifizieren.

Sie sehen nicht nur "viel Traffic", sondern klar: Welche Seite, welcher Bereich, welche Version.

2. Eindeutige Nutzer:innen & Wiederkehrer

Was: Wie viele Personen / Browser Ihre Doku nutzen und ob sie zurückkommen.

Technische Voraussetzungen

• Analytics-Tool mit Sessions/User-Logik.

• Gleiches Tracking-Snippet wie oben.

Kein zusätzlicher Code in AsciiDoc nötig. Entscheidend ist, dass alle Doku-Seiten das Snippet nutzen.

Wo messen?
Standard-Reports in Analytics:

• "Users / Unique Visitors"

• "New vs. Returning"

Filterbar nach Pfaden oder doc-id-Bereichen.

Beispiel: Nur doc-area=api → Wie viele Nutzer arbeiten regelmäßig mit API-Doku?

3. Verweildauer & Scrolltiefe

Was: Lesen Nutzer den Inhalt oder brechen sie ab?

Technische Voraussetzungen

• JavaScript erlaubt.

• Events an Analytics oder eigenes Backend.

AsciiDoc-Integration: Globales Include – verwenden Sie sendBeacon() für zuverlässige Übertragung:

ifdef::backend-html5[]

++++
<script>
  (function() {
    const docMeta = document.querySelector('meta[name="doc-id"]');
    const docId = docMeta ? docMeta.content : 'unknown';
    let maxScroll = 0;

    window.addEventListener('scroll', () => {
      const scrolled = (window.scrollY + window.innerHeight) 
        / document.body.scrollHeight * 100;
      if (scrolled > maxScroll) {
        maxScroll = scrolled;
      }
    });

    // sendBeacon ist zuverlässiger als fetch in beforeunload
    window.addEventListener('beforeunload', () => {
      const data = JSON.stringify({
        docId: docId,
        depth: Math.round(maxScroll)
      });
      navigator.sendBeacon('/api/scroll-depth', data);
    });
  })();
</script>
++++

endif::[]

Hinweis: Das beforeunload-Event blockiert in modernen Browsern oft asynchrone Requests. navigator.sendBeacon() löst dieses Problem, da es Daten auch beim Schließen des Tabs zuverlässig sendet. Alternativ können Sie Events auch periodisch senden (z. B. alle 30 Sekunden).

Wo messen?

In Ihrem Event-Dashboard: Durchschnittliche Scrolltiefe je doc-id.

Interpretation:

• <25 %: Titel/Intro stimmen nicht oder Inhalt irrelevant.

• 50–75 %: normal.

• ~100 % bei Troubleshooting-Seiten: gut, Nutzer suchen aktiv nach Lösung.

4. On-Page-Feedback („Hat geholfen?“)

Was: Schnelle Qualitätsbewertung pro Seite.

Technische Voraussetzungen

• Kleines HTML-Widget.

• Event-Endpoint im Backend oder Analytics als Eventziel.

AsciiDoc-Beispiel

ifdef::backend-html5[]

++++
<div id="doc-feedback">
  War diese Seite hilfreich?
  <button data-feedback="yes">Ja</button>
  <button data-feedback="no">Nein</button>
</div>
<script>
  (function() {
    const docMeta = document.querySelector('meta[name="doc-id"]');
    const docId = docMeta ? docMeta.content : 'unknown';
    
    document.querySelectorAll('#doc-feedback button')
      .forEach(btn => btn.addEventListener('click', () => {
        const value = btn.dataset.feedback;
        // feedbackEvent({ docId, value });
      }));
  })();
</script>
++++

endif::[]

Wo messen?

Aggregation pro doc-id:

helpful_rate = yes / (yes + no)

Nutzen:

• Ranking: Welche Seiten liefern den meisten Mehrwert?

• Priorisierung: Seiten mit vielen Aufrufen + schlechter Bewertung zuerst verbessern.

5. Suche & Findbarkeit

Was: Finden Nutzer, was sie brauchen?

Technische Voraussetzungen

• Suchfunktion im Doku-Portal.

• Logging der Suchbegriffe + Treffer.

AsciiDoc-Anknüpfung

Wenn Ihre Suche im Frontend läuft:

ifdef::backend-html5[]

++++
<form id="doc-search">
  <input name="q" />
  <button type="submit">Suche</button>
</form>
<script>
  document.getElementById('doc-search')
    .addEventListener('submit', function(e) {
      e.preventDefault();
      const query = this.q.value;
      // searchEvent({ query });
      // Dann eigentliche Suche ausführen
    });
</script>
++++

endif::[]

Wo messen?

• Liste aller Suchanfragen.

• Suchanfragen ohne Treffer.

• Begriffe, die auf falsche Seiten führen (hoher Absprung).

Daraus optimieren Sie: Seitentitel, Synonyme und Struktur Ihres Inhalts.

6. Task Success & Ticket-Deflection

Hier verbinden Sie Dokumentation mit Support-Kosten. Das ist intern oft der stärkste Hebel.

a) Task Success

Was: Anteil der Nutzer, die eine definierte Aufgabe mit Hilfe der Doku erfolgreich lösen.

Technische Voraussetzungen

• Definierte Task-Flows (z. B. „API-Key einrichten“).

• Seiten, die zu diesem Flow gehören, tragen ein Attribut.

AsciiDoc-Beispiel

= API Key erstellen
:doc-id: api-key-create
:task-flow: api-key-setup

Im Tracking-Snippet (Meta-Tag-Ansatz):

<script>
  const flowMeta = document.querySelector('meta[name="task-flow"]');
  const docMeta = document.querySelector('meta[name="doc-id"]');
  
  if (flowMeta && docMeta) {
    // taskStepEvent({
    //   flow: flowMeta.content,
    //   docId: docMeta.content
    // });
  }
</script>

Erfolgsmessung: Erfolg, wenn Nutzer die Zielseite erreichen (z. B. "Erfolgreich verbunden"-Seite) oder eine Aktion ausführen (z. B. API-Key speichern; Event aus Produkt).

Wo messen? Funnel pro task-flow: Einstieg → Zwischenschritte → Erfolg. Sie sehen, wo Nutzer aussteigen und welche Seiten im Flow optimiert werden müssen.

b) Ticket-Deflection

Was: Wie viele Support-Anfragen vermeiden Ihre Inhalte?

Technische Voraussetzungen

• Support-Formular oder Help-Widget mit Artikel-Referenz.

• Mapping von Tickets zu doc-id.

Konkreter Ansatz: Im Help-Widget sehen Nutzer Artikel-Vorschläge. Wenn sie trotzdem ein Ticket erstellen, senden Sie die zuletzt angesehene doc-id mit.

Auswertung:

• Themen mit vielen Tickets trotz Doku → Inhalt unklar.

• Drop in Tickets nach Update eines Artikels → messbarer Erfolg.

7. Interne Qualitätsmetriken

Diese Kennzahlen hängen direkt mit Ihrem AsciiDoc-Setup zusammen.

Beispiele:

• Anteil veralteter Seiten (:doc-version: vs. Produktversion).

• Broken Links (per Link-Check im CI).

• Aktualisierungszeit nach Release (Commit-Zeitstempel).

AsciiDoc-Unterstützung: Attribute wie :last-review: 2025-10-15. Tools / Linter lesen diese Attribute aus und erzeugen Berichte.

PDF-Export messbar machen

PDF kann keine JS-Events senden. Sie machen es über indirekte Signale messbar.

8. Trackbare Links aus PDF

Nutzen Sie pro PDF eine eindeutige Kurz-URL:

Weitere Infos:
link:https://docs.example.com/go/getting-started-pdf[Online-Dokumentation]

Diese URL leitet intern auf die echte Seite. Sie messen:

• Wie oft Leser:innen vom PDF zurück zur Online-Doku springen.

• Welche PDFs überhaupt genutzt werden.

9. QR-Codes

Nutzen Sie doc-id, um QR-Codes zu erzeugen.

image::qrcode-getting-started.png[Feedback geben]

QR-Ziel z. B.: https://docs.example.com/f/{doc-id}

Dort: Feedback-Formular oder Link zur aktualisierten Version.

10. Metadaten

Setzen Sie im PDF-Generator: Title, Subject, Keywords mit doc-id und Produkt. So können interne Systeme (DAM, Intranet, DMS) Nutzung und Versionen besser zuordnen.

Konkrete Minimal-Implementierung für Ihr Team

Wenn Sie mit wenig Aufwand starten wollen, reicht dieses Setup:

In jeder AsciiDoc-Seite:

= Titel
:doc-id: <eindeutig>
:doc-area: <bereich>
:doc-version: <version>

Ein globales HTML-Include

• Pageview mit doc-id (über Meta-Tags oder data-Attribute).

• Scrolltiefe-Event (mit sendBeacon für Zuverlässigkeit).

• Optionale Feedback-Buttons.

Ein einfaches Backend oder Analytics

Pro doc-id:

• Pageviews

• Scrolltiefe

• Feedback-Quote

Monatliche Auswertung

• Top 20 Seiten nach Aufrufen.

• Seiten mit vielen Aufrufen und schlechtem Feedback.

• Suchbegriffe ohne Treffer.

• Tickets pro Thema vor/nach Doku-Updates.

Damit schaffen Sie messbaren Mehrwert: Sie sehen schwarz auf weiß, welche Inhalte wirken und wo Sie nachschärfen.

Anhang: Technische Hinweise zur Implementierung

Attribut-Substitution in AsciiDoc

AsciiDoc substituiert Attribute standardmäßig nicht innerhalb von Passthrough-Blöcken (++++...++++). Dies ist ein häufiger Stolperstein.

Lösung 1 – Meta-Tags im Dokumentkopf:

Generieren Sie Meta-Tags außerhalb des Passthrough-Blocks und lesen Sie diese per JavaScript aus.

:doc-id: getting-started

// Im Docinfo-Header oder Template:
<meta name="doc-id" content="{doc-id}">

Der Meta-Tag wird korrekt substituiert, weil er außerhalb des Passthrough-Blocks steht. Im JavaScript lesen Sie dann:

const docId = document.querySelector('meta[name="doc-id"]').content;

Lösung 2 – subs-Attribut:

In manchen AsciiDoc-Versionen können Sie [subs=attributes] vor dem Passthrough-Block verwenden:

[subs=attributes]
++++
<script>
  const docId = '{doc-id}';
</script>
++++

Testen Sie dies mit Ihrer AsciiDoc-Version, da das Verhalten variieren kann.

Lösung 3 – data-Attribute auf Container-Elementen:

[id="tracking-container",data-doc-id="{doc-id}"]
--
Inhalt
--

beforeunload und sendBeacon

Das beforeunload-Event ist problematisch für Analytics:

• Moderne Browser blockieren oft asynchrone Requests (fetch, XMLHttpRequest).

• Mobile Browser unterdrücken das Event häufig komplett.

• Safari hat besonders strikte Einschränkungen.

Empfehlung: Verwenden Sie navigator.sendBeacon(). Diese Methode wurde speziell für diesen Anwendungsfall entwickelt und sendet Daten auch beim Schließen des Tabs zuverlässig.

window.addEventListener('beforeunload', () => {
  const data = JSON.stringify({ docId, depth: maxScroll });
  navigator.sendBeacon('/api/analytics', data);
});

Alternative: Events periodisch senden (z. B. alle 30 Sekunden) statt nur beim Verlassen. So verlieren Sie maximal 30 Sekunden an Daten.

setInterval(() => {
  navigator.sendBeacon('/api/scroll-depth', JSON.stringify({
    docId,
    depth: Math.round(maxScroll)
  }));
}, 30000);