Technische Dokumente in AsciiDoc erstellen
Erstellen Sie das Handbuch für ein E-Auto. So organisieren, schreiben und teilen Sie technische Dokumente in AsciiDoc.
Technische Redakteure leben an der Schnittstelle von Innovation und Verständlichkeit. Ihre Leidenschaft ist es, Lesern die komplexen Welten neuer Produkte und bahnbrechender Technologien zu erschließen. Dabei ist jeder Tag eine neue Lernreise, die nicht nur ihr Wissen erweitert, sondern auch ihre Fähigkeit, dieses Wissen klar und zugänglich zu vermitteln.
Heute wollen wir Ihnen ein neues Werkzeug mit an die Hand geben, um Dokumentationen auf effektive Weise zu erstellen. Dazu erstellen wir gemeinsam das Benutzerhandbuch für ein fiktives Elektroauto. Unser Ziel ist es, Ihnen einen umfassenden Leitfaden an die Hand zu geben, der Sie durch den gesamten Workflow führt - von der ersten Planung bis zur finalen Publikation.
Dieser Guide erklärt Ihnen die Prozesse hinter technischen Dokumenten. Wie sie die einzelnen Befehle konkret umsetzen, können Sie in unserem Handbuch nachlesen. Wir haben es an den relevanten Stellen stets für Sie verlinkt.
Für die Erstellung dieser Dokumentation nutzen wir adoc Studio, eine fortschrittliche Schreibumgebung, die speziell für technische Dokumentationen entwickelt wurde. adoc Studio basiert auf AsciiDoc, einer leichtgewichtigen Auszeichnungssprache, die für ihre Flexibilität und Einfachheit bekannt ist. Auch wenn Sie sich entscheiden, mit einem anderen AsciiDoc-kompatiblen Tool zu arbeiten, werden die in diesem Blog geteilten Prinzipien und Techniken universell anwendbar sein. AsciiDoc ist - im Gegensatz zu anderen Markup-Sprachen - auf dem Weg zur Standardisierung. Dadurch sind .adoc Dateien - unabhängig vom Editor - stets miteinander kompatibel.
Lassen Sie uns nun gemeinsam in das Projekt eintauchen.
Zurück zur Übersicht
Projektplanung & Vorbereitung
Beim Verfassen technischer Dokumente ist es wichtig, Konzepte präzise und einfach darzustellen. Um das effizient umzusetzen, müssen Sie Ihre Leser kennen. Überlegen Sie also stets, wer Ihre Zielgruppe ist. Was wissen die Leser bereits über das Produkt? Welche Fachbegriffe müssen erklärt werden, bevor sie verwendet werden?
Wer sind Ihre Leser?
Ihr erster Schritt ist die sorgfältige Recherche Ihrer Zielgruppe. Sie müssen hierbei nicht stets das Rad neu erfinden. In vielen Fällen haben Sie bereits eine klare Vorstellung oder gar Kontakt zu Ihren Lesern. Das spart natürlich Zeit und Geld. Sollte dies nicht der Fall sein, können Sie Ihre Leser durch eigene Internetrecherche oder bei Veranstaltungen wie Fachmessen besser kennenlernen. In Anwender-Interviews erhalten Sie einen Überblick über deren Verständnis und Kentnissstand. Doch wie viele Menschen sollten Sie befragen? Eine Daumenregel besagt, so lange nachzufragen, bis sich die Antworten wiederholen. Nach 3-5 Interviews sollten Sie jedoch einen ersten, groben Überblick erhalten haben.
Das Interesse an E-Mobilität ist über die Jahre kontinuierlich gewachsen. Um die gesamte Bandbreite an Nutzern abzudecken, befragen wir verschiedene Gruppen an Nutzern: Fahrer, die bereits ein E-Auto besaßen und solche, die noch nie in einem Elektroauto gefahren sind.
Die Rolle von Fachexperten
Sie kennen nun den Kentnissstand Ihrer Leser? Dann ist es jetzt an der Zeit, dass Sie selbst Experte Ihres Themas werden. Hierfür befragen wir Fachexperten. SMEs (für Subject Matter Experts), wie sie im Englischen abgekürzt werden, sind ein zentraler Ansprechpartner für Redakteure. Sie achten auf Richtigkeit und geben Ihren Texten Glaubwürdigkeit. Gepaart mit eigener Recherche geben Fachexperten Ihnen das nötige Wissen, um Konzepte detailliert aber verständlich für Ihre Leser zu erklären.
Für unser Beispiel kann eine ganze Bandbreite an Experten relevant sein: Automobil-Ingenieure, Software-Ingenieure für Fahrzeugelektronik, Energie- und Ladetechnik-Experten und mehr.
Struktur & Aufbau einer AsciiDoc Dokumentation
Sie haben Ihre Hausaufgaben gemacht? Dann steigen wir nun in unsere Schreibumgebung ein und geben unserem Projekt eine Gliederung. Wir erstellen ein Sammeldokument und widmen jedem Punkt der Gliederung ein eigenes Kapitel. Durch unsere bisherige Recherche haben wir uns auf die folgende Gliederung für die Bedienungsanleitung festgelegt:
Ausgewogen ist eine Gliederung dann, wenn die Anzahl der Abschnitte und Unterabschnitte in jedem Kapitel nicht zu stark voneinander abweichen. Es ergibt nicht viel Sinn, wenn ein Kapitel nur einen Unterabschnitt oder Abschnitt enthält.
Bevor wir nun mit dem Schreiben beginnen, noch ein Tipp am Rande. Nutzen Sie den Dokumentkopf, das heißt allen Zeilen, die sie über dem Titel eingeben, um Ihr Dokument in Inhalt und Gestaltung anpassen. Ein Beispiel: Schreiben Sie :toc: in den Dokumentkopf. Sie haben nun ein dynamisches Inhaltsverzeichnis, das - zur Zeit - die erste Gliederungsebene umfasst. Anpassungen an der Anzahl an Ebenen und der Positionierung des Inhaltsverzeichnisses sind ebenfalls möglich.
Jetzt haben wir aber genug geplant. Lassen Sie uns mit dem Schreiben beginnen.
Zurück zur Übersicht
Schreiben in AsciiDoc
Über die Jahre hat sich AsciiDoc als Auszeichnungssprache der Wahl für technische Dokumente bewährt. Der große Vorteil: Der Quellcode bleibt stets gut lesbar. Das bedeutet der Einstieg ist vergleichsweise einfach. Gleichzeitig hat AsciiDoc einen hohen Funktionsumfang, wodurch komplexe Projekte mit Leichtigkeit umgesetzt werden können.
AsciiDoc trennt Gestaltung von Inhalt. So konzentrieren Sie sich auschließlich auf das Schreiben. Das Dokument-Layout können Sie jederzeit, ohne den Text anzupassen, verändern. Dazu kommen wir später.
Wie in jeder Auszeichnungssprache können Sie auch einzelne Worte fett, kursiv oder anders formatieren. Anbei eine Liste der wichtigsten Auszeichnungen in AsciiDoc:
Listen
Ein Grundprinzip der technischen Dokumentation ist es, Konzepte klar und einfach zu erklären. Fließtext ist hierbei nicht immer das beste Mittel. So verwenden wir für unser Beispielprojekt Listen, um:
Aufzählungen ohne Reihenfolge (z.B. zur Auflistung aller Navi-Funktionen) als ungeordnete Liste
Schritt-für-Schritt Erklärungen mit geordneten (bzw. numerierten) Listen zu erstellen
Pflegeanweisungen für die Sitze als Checkliste anzugeben
Visualisierungen einbetten
Der Spruch klingt zwar mittlerweile mehr wie ein Klischee, aber dennoch steckt Wahrheit drin: "Ein Bild sagt mehr als 1000 Worte". Bilder, Tabellen und mehr helfen dabei, komplexe Sachverhalte zu veranschaulichen. Sie geben Ihren Lesern Orientierung und helfen dabei Instruktionen zu verstehen.
Ein Tipp, um Tabellen noch schneller einzufügen: Nutzen Sie die Apple Textersetzung in den Systemeinstellungen. So können Sie einen Text durch einen Anderen ersetzen lassen. Ich persönlich schreibe nur table(), um eine Tabelle mit Titel, 3 Spalten und 2 Reihen zu erstellen. Hier die Tabelle, falls Sie es mir nachmachen möchten.
|===
| Titel 1 | Titel 2 | Titel 3
| Spalte 1 | Spalte 2 | Spalte 3
| Spalte 1 | Spalte 2 | Spalte 3
|===
Blöcke in AsciiDoc
Darüber hinaus bietet AsciiDoc Blöcke, um Informationen aus dem Textfluss herauszunehmen. Die Hinweise sind eines der wichtigsten Blockelemente. Sie ermöglichen Ihnen Tipps, Warnungen, Anmerkungen und mehr auszusprechen. So geben Sie Ihren Nutzern mit TIP: beispielsweise einen Tipp zum batterieschonenden Laden.
Weitere Elemente wie Zitate, Fußnoten, Benutzerschnittstellen (z.B. um Tastaturkürzel zu visualisieren) sind ebenfalls schnell integriert. Denken Sie stets dran, auf Glaubwürdigkeit und Verständlichkeit in Ihren Texten zu setzen.
Digitale Navigation
Ein weiteres Grundprinzip technischer Dokumentation ist die intuitive Bedienung der Texte. Handbücher leben schon längst nicht mehr nur in Papierformat. Somit können Sie Texte nun wesentlich intelligenter aufbauen.
Querverweise
Wir setzen Querverweise innerhalb unseres Handbuchs, um einzelne Kapitel miteinander zu verbinden. Sie haben erklärungsbedürftige Begriffe in Ihren Dokumenten? Dann verlinken Sie ihn an jeder Stelle auf die Definition im Glossar. So muss der Begriff nur einmal erklärt werden.
Ein Tipp, um Fehler durch veränderte Titel zu vermeiden: Setzen Sie eine Anker-ID vor Überschriften. Das hat den großen Vorteil, dass nicht die Überschrift als Verweis gesetzt wird und somit Änderungen des Titels keinen Einfluss auf die Referenz haben.
Hyperlinks
Wir setzen Hyperlinks ins Internet, um auf externe Quellen zu verweisen. Unser Tipp für wiederkehrende Links: Definieren Sie die URL als Attribut im Dokumentkopf, um ihn jederzeit zu wiederholen, ohne die gesamte URL einzugeben. Ein weiterer Vorteil: Sollte sich der Pfad ändern, müssen Sie diesen nur an einer Stelle ändern.
Intelligente Dokumente
Der wahrscheinlich größte Vorteil an AsciiDoc ist die Erstellung intelligenter Dokumente. Mit Hilfe von Attributen und Bedingungen erstellen Sie ein Master-Dokument, dass sich wie ein Baukastensatz an die Anforderungen Ihrer Leser anpasst.
Attribute
Sie werden schnell den Wert von Attributen in AsciiDoc schätzen lernen. Diese kleinen Helfer ermöglichen es Ihnen, Informationen im gesamten Dokument konsistent zu halten ohne an Flexibilität einzubüßen.
Es ist sehr wahrscheinlich, dass Sie beispielsweise den Namen des Elektroautos, diverse Sicherheitshinweise oder URLs auf Ihre Firmenwebsite mehrfach erwähnen. Sollten nun an dem Text Änderungen notwendig werden, müssen Sie nicht jede Stelle einzeln anpassen. Stattdessen definieren Sie ein Attribut zu Beginn des Dokuments und fügen es überall ein, wo Sie es benötigen.
Bedingungen
Nicht jeder Inhalt ist für alle Leser relevant. Unser E-Auto ist in verschiedenen Modell-Typen erhältlich und die Ausstattung ist ebenfalls konfigurierbar. Haben Fahrer also Ledersitze anstelle von Stoffsitzen für ihr Auto konfiguriert, muss sich das Handbuch an die Konfiguration anpassen.
Das führt uns zu den Bedingungen in AsciiDoc. Bedingungen können eingesetzt werden, um Texte ein- oder auszublenden. Hierfür definieren wir ein Attribut und setzen es in eine ifdef Bedingung ein. Jetzt wird dieser Text nur ausgegeben, wenn das Attribut "ledersitz" aktiviert wurde.
Exkurs: Gestaltung
Wie bereits erwähnt, sind in AsciiDoc Gestaltung und Inhalt voneinander unabhängig. Nachdem wir nun den ersten Entwurf des Benutzerhandbuchs inhaltlich erstellt haben, können wir uns Gedanken zur Gestaltung machen. Hier unterscheiden sich die Ansätze. So muss AsciiDoc nativ über Skripte und Konverter ausgegeben werden. In diesem Prozess kann dann ein Stylesheet hinterlegt werden. Dieser Stil muss jedoch für jede Ausgabe einzeln und in unterschiedlichen Sprachen vorher festgelegt werden.
Wir gehen den einfachen Weg und nutzen adoc Studio's mitgelieferten Produktstile. Hier haben wir eine Auswahl an Templates zur Verfügung, die für jedes Ausgabeformat gelten. Das heißt wir nutzen für HTML wie auch PDF die gleiche Stil-Datei. Ein Klick auf den Stil und schon wird unser gesamtes Projekt umgestaltet. Das ist bereits ein guter Start, wir wollen den Stil aber an die Corporate Identity unseres Auftraggebers anpassen. Dafür duplizieren wir einen Stil, der uns gefällt und bearbeiten die Datei. Mit einfachen CSS Kenntnissen erstellen wir einen individuellen Stil für unser Projekt und speichern es für kommende Aufträge ab. Anpassungen der Schriftart, Dokumentfarben und mehr sind ein Kinderspiel.
Zurück zur Übersicht
Redaktion und Zusammenarbeit
Sie haben das Handbuch fertig geschrieben? Dann haben Sie sich nun eine Verschnaufspause verdient. Geben Sie Ihr Dokument einer Person Ihres Vertrauens und holen Sie Feedback ein. Lassen Sie Ihren Text auf Inhalt und Sprache überprüfen. Sind Konzepte inhaltlich verständlich erklärt? Lassen sich die Anleitungen von Anwendern nachvollziehen und umsetzen? Hier ist es sinnvoll, Ihre Fachexperten in das Lektorat mit einzubeziehen. Sie können Ihnen inhaltliche Fehler aufzeigen.
Damit sie nun nicht die ganze Zeit neben Ihren Korrekturlesern sitzen müssen, gibt es in AsciiDoc die Kommentarfunktion. Kommentare werden direkt im Quelltext verfasst. Wie in Programmiersprachen werden Zeilen nicht mit ausgegeben, wenn sie mit // "auskommentiert" werden. Übrigens: Die Ähnlichkeiten zu Programmiersprachen haben dazu geführt, dass AsciiDoc Texte nach der Philosophie "Docs as Code" verfasst und verwaltet werden. Mehr dazu in diesem Blogbeitrag von uns.
Ein Dokument, viele Ausgaben
Unser "Master-Dokument" ist nun soweit erstellt und korrigiert worden. Jetzt können wir unser Handbuch je nach Konfiguration, individuell ausgeben. Der Schlüssel liegt im Multi-Target Publishing (oder Single-Source Publishing). Das Konzept ist einfach: Sie haben ein einziges Quelldokument und erstellen daraus sämtliche Ausgaben, die sich in Format (HTML, PDF, ePub, ...) oder Inhalt (z.B. die Konfiguration des Autos) unterscheiden können. Da wir bereits die Attribute im Text definiert haben, müssen wir bei der Ausgabe nur noch alle aktivieren, die für den Anwender relevant sind.
In adoc Studio lässt sich die Ausgabe komplett über die App erstellen. In traditionellen Workflows müssen Sie oft komplexe Skripte im Terminal ausführen, um verschiedene Ausgabeformate zu generieren. Dieser "Terminal-Terror" gehört jedoch nun der Vergangenheit an. Sie definieren die Ausgabe als Produkt und wählen Format, Stil und Attribute aus.
Herzlichen Glückwunsch! Sie haben nun Ihre erste Dokumentation in AsciiDoc erstellt. Doch die Reise ist hier nicht zu Ende. Sie sollten Ihre Dokumentation stets aktuell halten und - mit Hilfe von Feedback - stets verbessern. Wir ermutigen dazu, dass Sie Ihre Dokumente regelmäßig überarbeiten und optimieren.
Denken Sie daran, Übung macht den Meister, daher zögern Sie nicht, Ihre neu erworbenen Fähigkeiten in der Praxis anzuwenden. Sollten Sie hierfür noch nach einer Schreibumgebung suchen, laden wir Sie ein adoc Studio auszuprobieren.
