Drei Autoren, ein Benutzerhandbuch: Einheitliche Terminologie mit HelpNDoc

Mira nennt es Dashboard. Leo nennt es Systemsteuerung. Dann öffnet Sana die fertige Anwendung und sieht Arbeitsbereich. Derselbe Bildschirm, drei Namen. Irgendwo sucht ein Leser gerade nach den anderen beiden.

Das Handbuch ist durch drei Paar Hände gegangen. Mira hat das Einstiegskapitel anhand eines frühen Entwurfs geschrieben. Leo hat sich an technischen Notizen orientiert. Sana bereitet die Veröffentlichung vor und gleicht das Handbuch mit der fertigen Anwendung ab. Niemand wollte Verwirrung stiften, doch die wechselnden Namensentscheidungen eines Produktteams sollten nicht zum Problem der Leser werden.

So bringt unser fiktives Team mit HelpNDoc wieder Ordnung hinein: Variablen für wiederkehrende Namen, Snippets für gemeinsam genutzte Erklärungen und projektweites Suchen und Ersetzen, um ältere Kapitel zu aktualisieren. Damit kann jeder Autor etwas Nützlicheres weitergeben als die Bitte, “doch auf einheitliche Begriffe zu achten”.

🧭 Erst klären, was gemeint ist, dann den Begriff ändern

Bevor Sie eine Bezeichnung ändern, sollten Sie sicherstellen, dass alle vom Gleichen sprechen. Leo legt zunächst die Terminologie fest, einschließlich der Ausnahmen.

Mira speichert und schließt das HelpNDoc-Projekt und gibt die aktuelle Kopie an Leo weiter. Als er das Kapitel zur Administration ergänzt, fällt ihm auf, dass seine “Systemsteuerung” Miras “Dashboard” verdächtig ähnlich sieht.

Er prüft die Anwendung. Beide Bezeichnungen meinen den Hauptbildschirm, der inzwischen Arbeitsbereich heißt. Bevor er den Text anfasst, hält er im Projektkommentar eine kurze Notiz für das Team fest:

Die zweite Zeile ist wichtig. Wer zu schnell ersetzt, schickt seine Leser womöglich in den “Windows-Arbeitsbereich”. Das klingt offiziell, hilft aber niemandem dabei, die Einstellungen zu finden.

Halten Sie Terminologieentscheidungen kurz und konkret fest: die gewählte Bezeichnung, ihre Bedeutung und mögliche Ausnahmen. HelpNDoc kann die Formulierung wiederverwenden, aber was die Wörter bedeuten, muss weiterhin ein Mensch entscheiden.

🏷️ Wiederkehrende Namen zentral in der Bibliothek pflegen

Überall den richtigen Namen einzutippen funktioniert, bis das Produktteam ihn wieder ändert. Mit einer Variablen können Autoren eine im ganzen Handbuch verwendete Bezeichnung an einer einzigen Stelle pflegen.

Leo könnte einfach alle alten Bezeichnungen durch “Arbeitsbereich” ersetzen. Damit wäre das heutige Problem gelöst, doch bei der nächsten Umbenennung müsste Sana erneut das ganze Handbuch durchsuchen.

Stattdessen wählt er in HelpNDoc Start > Bibliothek > Element hinzufügen und erstellt eine Variable mit dem Namen TermWorkspace und dem Wert Arbeitsbereich. Anhand des Namens erkennen die Autoren das Bibliothekselement; der Wert ist der Text, den die Leser später sehen.

Wenn Leo neue Anweisungen schreibt, fügt er TermWorkspace aus der Bibliothek überall dort ein, wo der Bildschirmname stehen soll. Dazu kann er das Element auswählen und auf In Thema einfügen klicken oder es in den Themeneditor ziehen. Die Anleitung zum Einfügen von Bibliothekselementen erklärt die verschiedenen Möglichkeiten.

Bei der Generierung der Dokumentation setzt HelpNDoc den aktuellen Wert der Variablen ein. Die fertige Anweisung lautet dann: “Öffnen Sie den Arbeitsbereich und wählen Sie ein Projekt aus.”

Wird der Bildschirm später erneut umbenannt, kann das Team die Variable einmal ändern und die Dokumentation neu generieren. Jedes Thema, das diese Referenz verwendet, übernimmt den neuen Wert.

Sie müssen allerdings nicht aus jedem Substantiv eine Variable machen. Beginnen Sie mit Namen, die häufig vorkommen oder sich voraussichtlich ändern werden. Sana braucht eine hilfreiche Bibliothek, kein zweites Handbuch, das das erste erklärt.

🔎 Auch die vorhandenen Kapitel auf den neuesten Stand bringen

Der neue Text verwendet die Variable, aber in Miras älteren Kapiteln steht noch “Dashboard”. HelpNDoc kann diese vorhandenen Wörter mit demselben Bibliothekselement verknüpfen, sofern Leo bei jedem Treffer prüft, was gemeint ist.

Leo öffnet Suchen und Ersetzen mit Ctrl+Shift+F, legt als Suchbereich das gesamte Projekt fest und sucht nach Dashboard. Er kann die Suche auf ganze Wörter beschränken, um die Ergebnisse einzugrenzen, und bei Bedarf die Groß- und Kleinschreibung berücksichtigen.

Er prüft die Treffer und ersetzt die Bezeichnungen für den Hauptbildschirm der Anwendung durch das Bibliothekselement TermWorkspace, statt erneut einfachen Text einzusetzen. Anschließend wiederholt er den Vorgang für Systemsteuerung. Tatsächliche Verweise auf die Windows-Systemsteuerung lässt er unverändert.

Eine übereinstimmende Formulierung hat nicht immer dieselbe Bedeutung. Deshalb liest er den jeweiligen Satz, bevor er eine weitreichende Änderung vornimmt. Die Anleitung zum Suchen und Ersetzen in HelpNDoc zeigt, wie sich gewöhnlicher Text durch Bibliotheksreferenzen ersetzen lässt.

Nach dem Ersetzen liest Leo die bearbeiteten Absätze noch einmal. Ein neues Wort kann inhaltlich stimmen und trotzdem nicht zum Artikel oder Verb im bisherigen Satz passen. Auch Überschriften und Screenshots prüft er gesondert, statt davon auszugehen, dass eine Textersetzung alles erledigt hat.

Jetzt beziehen die alten und die neuen Kapitel den Bildschirmnamen aus derselben Quelle.

🧩 Neben der Bezeichnung auch die Erklärung gemeinsam pflegen

Überall denselben Namen zu verwenden ist ein guter Anfang. Beschreiben zwei Kapitel den Bildschirm jedoch unterschiedlich, erhalten die Leser womöglich trotzdem zwei Versionen der Wahrheit.

Genau das fällt Leo auf. Miras Einführung und sein Administrationskapitel beschreiben beide den Arbeitsbereich, aber einer der Texte verspricht Informationen, die dort gar nicht angezeigt werden.

Er stimmt eine kurze, zutreffende Definition mit dem Team ab:

Der Arbeitsbereich zeigt Ihre Projekte und die letzten Aktivitäten an. Öffnen Sie von hier aus ein Projekt, um weiterzuarbeiten.

Da der Absatz in mehreren Themen benötigt wird, wandelt Leo ihn in ein Snippet um, das im HelpNDoc-Projekt gespeichert wird. Er markiert den freigegebenen Text, klickt mit der rechten Maustaste darauf und wählt In Snippet konvertieren…. Auf die Frage, ob die Auswahl durch eine Referenz auf das neue Snippet ersetzt werden soll, antwortet er mit Ja.

Im anderen Kapitel fügt er eine Referenz auf dasselbe Snippet ein. Damit verwenden beide Themen eine gemeinsame Textpassage.

Im Menü gibt es einen kleinen, aber wichtigen Unterschied: In Thema einfügen fügt eine wiederverwendbare Referenz hinzu, während Inhalt in Thema einfügen eine separate, bearbeitbare Kopie des Snippet-Inhalts in das Thema übernimmt. Für eine Definition, die das Team zentral pflegen möchte, wählt Leo die Referenz. Die Dokumentation zu Snippets erläutert beide Möglichkeiten.

Die Aufgabenverteilung ist einfach: Die Variable hält die Bezeichnung einheitlich, das Snippet die Erklärung. Ändert sich das Produkt, kann das Team den gemeinsamen Absatz an einer Stelle prüfen und aktualisieren. Leo hält außerdem fest, dass direkt in das Snippet eingegebene Namen bei Terminologieänderungen ebenfalls überprüft werden müssen.

🤝 Dem nächsten Autor eine hilfreiche Übergabe ermöglichen

Sana sollte Leos Entscheidungen nicht aus verstreuten Änderungen rekonstruieren müssen. Eine kurze Übergabenotiz zeigt ihr, was freigegeben ist, was sie wiederverwenden kann und was noch Aufmerksamkeit braucht.

Leo speichert und schließt das Projekt, bevor Sana die vereinbarte aktuelle Kopie öffnet. Seine Notiz enthält vier Punkte: den bevorzugten Begriff, die Variable TermWorkspace, das Snippet mit der gemeinsamen Definition und die Kapitel, die noch geprüft werden müssen.

Als Sana mit dem Kapitel zur Fehlerbehebung beginnt, schaut sie zuerst in die Projektbibliothek. Für den Hauptbildschirm fügt sie die vorhandene Variable ein; dort, wo Leser die Erklärung benötigen, verwendet sie das Snippet. Mit der Autovervollständigung über Ctrl+Space kann Sana freigegebene Bibliothekselemente schnell finden und einfügen, ohne ihren Gedankengang zu unterbrechen. Wie das funktioniert, erläutert die Dokumentation zur Tastatur-Autovervollständigung in HelpNDoc.

Da Leo das Snippet im Projekt gespeichert hat, wird es mit der Projektdatei weitergegeben. Bei extern verknüpften Dateien und benutzerdefinierten Vorlagen muss die Übergabe gesondert geprüft werden. Sonst bleibt vielleicht eine unverzichtbare Datei auf Leos Desktop zurück und genießt dort ihren vorzeitigen Ruhestand.

⚖️ Warum sich dieser Ablauf lohnt

Einheitliche Terminologie bedeutet nicht, dass drei Autoren wie ein einziger Roboter klingen müssen. Jeder kann seinen eigenen Stil behalten, ohne demselben Bildschirm drei verschiedene Namen zu geben.

Auch andere Schreibprogramme bieten nützliche Funktionen für wiederkehrende Formulierungen, etwa die Schnellbausteine in Word oder die automatischen Ersetzungen in Google Docs. Für dieses Team liegt der Vorteil von HelpNDoc darin, wie die einzelnen Funktionen in einem Dokumentationsprojekt zusammenspielen.

Leo kann vorhandene Wörter in Bibliotheksreferenzen umwandeln. Sana kann beim Schreiben freigegebene Bezeichnungen und Erklärungen wiederverwenden. Anschließend generiert sie die HTML-Hilfe und das PDF-Handbuch aus der gepflegten Quelle.

Verglichen mit dem Kopieren von Absätzen zwischen Kapiteln und dem separaten Korrigieren jeder Ausgabe gibt es damit weniger unabhängige Kopien, die nach jeder Änderung nachgezogen werden müssen. Der nächste Autor erhält sowohl die Entscheidung als auch das Material, mit dem sie sich umsetzen lässt.

📚 Zum Schluss die Fassung prüfen, die die Leser erhalten

Eine aufgeräumte Projektbibliothek ist schön, aber die Leser sehen sie nie. Entscheidend ist, ob die veröffentlichten Anweisungen in jedem Format verständlich und einheitlich sind.

Sana generiert die HTML-Hilfe und das PDF-Handbuch und führt anschließend die Einstiegsschritte in beiden Fassungen aus. Sie gleicht den Bildschirmnamen, die gemeinsame Definition, die Überschriften und die Screenshots mit der fertigen Anwendung ab.

Falls ein Begriff zwischen den Ausgaben unerwartet abweicht, prüft sie auch, ob eine buildspezifische Bibliothekselement-Überschreibung einen anderen Wert liefert. Sobald alles stimmt, generiert sie die geänderten Ausgaben erneut, verteilt die geprüften Dateien und hält die Projektversion für den nächsten Autor fest.

Endlich kann der Leser den Arbeitsbereich öffnen, ohne sich zu fragen, wo das Dashboard geblieben ist. Drei Autoren haben mitgewirkt, und ihre individuellen Schreibstile haben weiterhin Platz. Nur der Name des Bildschirms bleibt jetzt derselbe.

Laden Sie HelpNDoc herunter und probieren Sie denselben Ansatz mit einer wiederkehrenden Bezeichnung und einem gemeinsam genutzten Absatz in Ihrem Handbuch aus. Machen Sie daraus eine Variable und ein referenziertes Snippet und geben Sie dem nächsten Autor etwas Hilfreiches mit, selbst wenn Sie selbst der nächste Autor sind!