Die meisten Dokumentationswebsites von Unternehmen, die Codeblöcke enthalten, verwenden Stile, die Platzhalter kennzeichnen. Die Absicht soll klar sein, und die Leser sollen wissen, was sie ändern müssen, doch die Benutzererfahrung lässt zu wünschen übrig.
Dieselben Stile werden an anderer Stelle in der Dokumentation auch zur Hervorhebung, für UI-Bezeichnungen oder zur Syntax verwendet. Zu den gängigen Platzhaltern, die technische Redaktionsteams zur Kennzeichnung von Code-Blöcken verwenden und die auch als andere Stile eingesetzt werden, gehören:
- Kursivschrift
- {Klammern}
- Fett
- Beispielname_##
- ALL_CAPS
- Eine Kombination aus den oben genannten Punkten
- Etwas völlig anderes
Diese Überschneidungen machen die Nachverfolgung und Verwaltung von Platzhaltern komplexer, als sie sein sollte. Im kleinen Maßstab mag dies wie ein Ärgernis erscheinen. Doch wenn Dokumentationsbibliotheken wachsen und sich über Teams und Jahre hinweg ausbreiten, führt dies zu Problemen sowohl für Autoren als auch für Leser. Was eigentlich die Verwaltung von Platzhaltern vereinfachen soll, verkompliziert sie stattdessen, da dieselbe Formatierung an anderer Stelle wiederverwendet wird.
Das Ergebnis kann dazu führen, dass Sie sich in einer vertrauten Situation wiederfinden: Sie müssen die Platzhalterkonvention herausfinden und versuchen, alle zu aktualisieren, wenn Sie erfolgreich sein wollen. Wenn Sie einen Platzhalter übersehen, funktioniert der Befehl möglicherweise nicht wie erwartet. Es können weitere Probleme auftreten, wie Fehler, unerwartete Konfigurationen oder sogar Einstellungen, von denen Sie nicht wussten, dass sie geändert werden können. Andere Ansätze für Code-Blöcke bieten nur begrenzte Möglichkeiten:
- Statische Blöcke (mit oder ohne Syntaxhervorhebung) sind unverzichtbar, wenn Sie die Werte bereits kennen. Sie sind schnell und können direkt kopiert und ausgeführt werden. Diese eignen sich am besten, wenn Sie nichts ändern müssen.
- Inline-Editoren gehen ins andere Extrem und ermöglichen es Ihnen, Text direkt innerhalb des Code-Blocks zu aktualisieren, allerdings oft auf Kosten des Kontexts – das Rückgängigmachen wird unzuverlässig und kleine Fehler löschen die benötigte Struktur.
- Mit Entwickler-API-Editoren können Sie Abfragen in Echtzeit ausprobieren. Sie eignen sich hervorragend, wenn die Hauptzielgruppe aus Entwicklern besteht, die direkt mit APIs arbeiten. Unternehmensdokumentationen erfüllen jedoch umfassendere Aufgaben und Anwendungsfälle, und diese Art der Interaktivität fehlt oft dort, wo sie dennoch einen Mehrwert bieten würde.
Die Lücke schließen mit interaktiven Code-Blöcken
Unsere interaktiven Code-Blöcke schließen diese Lücke, indem sie einen historisch anfälligen Teil der Dokumentation (den Platzhalter) in etwas Klares, Bearbeitbares und Skalierbares verwandeln.
Sie erhalten denselben Befehl wie zuvor mit derselben Formatierung und Struktur, nur dass die Platzhalter nun zu bearbeitbaren Feldern geworden sind. Jedes Feld verfügt über eine eindeutige Beschriftung (wie zuvor), sodass Sie keine Symbole interpretieren oder sich auf Vermutungen verlassen müssen.
Sie aktualisieren die Werte direkt im Block, wobei der umgebende Kontext weiterhin sichtbar bleibt. Das bedeutet, dass Sie das Beispiel, den restlichen Inhalt der Seite und Ihre Eingaben alle an einem Ort sehen. So können Sie ein relevanteres Snippet erstellen, bevor Sie auf „Kopieren“ klicken.
Sie können diese Werte vor dem Kopieren ändern oder unverändert lassen und später in einem anderen Editor bearbeiten. In beiden Fällen bleibt die Struktur unverändert, und das, was Sie kopieren, entspricht genau dem, was Sie im Block sehen. Platzhalter in einem Codeblock, die denselben Namen haben, werden miteinander verknüpft. Wenn Sie den Wert eines Platzhalterfelds über dem Codeblock ändern, können alle verknüpften Felder gleichzeitig aktualisiert werden, sodass Sie Felder mit demselben Platzhalterwert konsistenter bearbeiten können. Dies hilft, potenzielle Such- und Ersetzungsfehler bei der Arbeit in einem Texteditor zu reduzieren.
Die Veränderung der Arbeitsweise
Dieser Wandel löst zwei Probleme auf einmal. Für Leser reduziert er das Rätselraten und beugt Fehlern vor. Das Entziffern von geschweiften Klammern oder spitzen Klammern gehört der Vergangenheit an. Für Autoren trennt er Semantik von Formatierung, sodass Platzhalter programmgesteuert nachverfolgt, geprüft und aktualisiert werden können. Dies ermöglicht Versionsverfolgung, Validierungsregeln und Konsistenz über alle Umgebungen hinweg. Bestehende Inkonsistenzen werden dabei korrigiert, was die Wartung der gesamten Bibliothek vereinfacht.
Interaktive Codeblöcke verwandeln einen der schwierigsten Aspekte der Dokumentation – stilbasierte Platzhalter – in etwas Präzises, Wartbares und Schnell zu Verwendendes. Die Benutzererfahrung wirkt durchdacht statt improvisiert. Und zum ersten Mal schafft die Verwaltung von Code-Beispielen in großem Maßstab Möglichkeiten zur Verbesserung statt Hindernisse.
Jetzt live in Software, SaaS und mehr
Diese Funktion ist bereits auf unserer Dokumentationswebsite für Software (Versionen 11.42, 11.40, 11.36 und 11.32) verfügbar. Für SaaS und andere zugehörige Websites ist sie unter https://documentation.commvault.com/ verfügbar.
Probieren Sie es aus, wenn Sie beim nächsten Surfen auf einen Code-Block stoßen – bearbeiten Sie ein paar Felder, klicken Sie auf „Kopieren“ und sehen Sie, wie viel einfacher der Einstieg ist, nachdem Sie ihn in Ihren Editor importiert haben.
Hinweise:
- Überprüfen Sie jeden Code sorgfältig, bevor Sie ihn ausführen, unabhängig davon, ob er aus einem interaktiven oder statischen Codeblock stammt.
- Wenn Sie eine Seite aktualisieren, nachdem Sie Platzhalter in einem interaktiven Codeblock geändert haben, werden alle geänderten Platzhalter auf ihre Standardwerte zurückgesetzt.
Erfahren Sie hier mehr über die Verwendung von Code-Blöcken.
