Die meisten Dokumentationswebsites von Unternehmen,die Code-Blö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 auch zur Hervorhebung,für UI-Bezeichnungen oder für die Syntax an anderen Stellen in der Dokumentation verwendet. Zu den gängigen Platzhaltern,die technische Redaktionsteams zur Kennzeichnung von Code-Blöcken verwendenunddie auch als andere Stile genutzt werden,gehören:
- Kursivschrift
- {Klammern}
- Fett
- Beispielname_##
- ALL_CAPS
- Eine Kombination aus den oben genannten Punkten
- Etwas völlig anderes
Diese Überschneidungen machen die NachverfolgungundVerwaltung von Platzhaltern komplexer,als sie sein sollte. Im kleinen Maßstab mag dies als Ärgernis empfunden werden. Doch wenn Dokumentationsbibliotheken wachsenundsich über TeamsundJahre hinweg ausbreiten,führt dies sowohl für Autoren als auch für Leser zu Problemen. 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 bekannten Situation wiederfinden: Sie müssen die Platzhalterkonvention herausfindenundversuchen,alle Platzhalter 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 z. B. Fehler,unerwartete Konfigurationen oder sogar Einstellungen,von denen Sie nicht wussten,dass sie geändert werden können. Andere Code-Block-Ansätze haben nur begrenzte Möglichkeiten:
- Statische Blöcke (mit oder ohne Syntaxhervorhebung) sind unverzichtbar,wenn Sie die Werte bereits kennen. Sie sind schnellundkönnen einfach kopiertundausgeführt werden. Diese eignen sich am besten,wenn Sie nichts ändern müssen.
- Inline-Editoren gehen ins andere Extremundermöglichen es dir,Text direkt innerhalb des Code-Blocks zu aktualisieren,jedoch oft auf Kosten des Kontexts – das Rückgängigmachen wird unzuverlässigundkleine Fehler löschen die benötigte Struktur.
- Mit Entwickler-API-Editoren können Sie Anfragen in Echtzeit ausprobieren. Sie eignen sich hervorragend,wenn die Hauptzielgruppe aus Entwicklern besteht,die direkt mit APIs arbeiten. Unternehmensdokumentationen erfüllen jedoch umfassendere AufgabenundAnwendungsfä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 Codeblö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,BearbeitbaresundSkalierbares verwandeln.
Sie erhalten denselben Befehl wie zuvor mit derselben FormatierungundStruktur,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 SeiteninhaltundIhre Eingaben alle an einem Ort sehen. Dies kann Ihnen helfen,ein relevanteres Snippet zu gestalten,bevor Sie auf „Kopieren“ klicken.
Sie können diese Werte vor dem Kopieren ändern oder sie unverändert lassenundspä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-undErsetzungsfehler bei der Arbeit in einem Texteditor zu reduzieren.
Der Wandel der Arbeitsweise
Dieser Wandel löst zwei Probleme auf einmal. Für Leser reduziert er das Rätselratenundbeugt Fehlern vor. Das Entziffern von geschweiften Klammern oder spitzen Klammern entfällt. Für Autoren trennt er Semantik von Styling,wodurch Platzhalter programmgesteuert nachverfolgt,geprüftundaktualisiert werden können. Das ermöglicht Versionsverfolgung,ValidierungsregelnundKonsistenz über verschiedene 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,WartbaresundSchnell zu Verwendendes. Die Benutzererfahrung wirkt durchdacht statt improvisiert. Und zum ersten Mal schafft die Verwaltung von Codebeispielen in großem Maßstab Möglichkeiten zur Verbesserung statt Hindernisse.
Jetzt live in Software,SaaSundmehr
Diese Erfahrung ist bereits auf unserer Dokumentationswebsite für Software (Versionen 11:42,11.40,11,36und11,32) verfügbar. SAASundanderen zugehörigen Websites auf https://documentation.commvault.com/ verfügbar.
Probieren Sie es aus,wenn Sie das nächste Mal beim Surfen auf einen Code-Block stoßen – bearbeiten Sie ein paar Felder,klicken Sie auf „Kopieren“undsehen 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 Siehier mehr über die Verwendung von Code-Blöcken.
