Technische Dokumentation in der High-Tech-Branche wird oft als Beiwerk abgetan. Wir zeigen, wie Sie damit echten Mehrwert für Ihr Produkt schaffen.
Technische Dokumentation als wertvolles Asset
Auch nach mehr als zwei Jahrzehnten als Tech Writer staune ich immer wieder darüber, wie groß die Lücke zwischen dem Potenzial und der Realität technischer Dokumentation ist.
In den letzten Jahren habe ich mich mit der Frage beschäftigt, wie technische Dokumentation in der High-Tech-Branche echten Produktmehrwert liefern kann, statt bloßes Anhängsel zu bleiben.
Erste Versuche mit verschiedenen Produkten haben mich vom Wert dieses Ansatzes überzeugt. Seither suche ich nach Gelegenheiten, die Idee weiterzuentwickeln. Nach sechs Monaten als Technical Writer bei DoiT möchte ich nun einige Erkenntnisse und neue Überlegungen mit Ihnen teilen.
Das Wichtigste zuerst
Technical Writer stoßen fast immer erst spät zum Engineering- oder Produktteam dazu (je nach Produktentwicklungsverständnis der jeweiligen Organisation). Schließlich ist heutzutage jeder zugleich Autor und Publisher. Solange Sie noch Early Adopters gewinnen, sind GitHub-Repositories, Blogbeiträge und Forendiskussionen oft der kosteneffizientere Weg zur Zielgruppe.
Erst wenn das Produkt diese Phase hinter sich hat und skaliert werden soll, kommt jemand auf den Gedanken, Technical Writer hinzuzuziehen. Aus meiner Erfahrung müssen diese als Erstes klare Spielregeln in Form von Konventionen aufstellen.
In einer Branche, die sich Innovation und Kreativität auf die Fahnen schreibt, mag es seltsam wirken, ausgerechnet Konventionen an den Anfang zu stellen. Doch Konventionen sind weder Feind der Innovation noch der Kreativität. Wer auf nicht kritischen Pfaden Konventionen folgt, reduziert die kognitive Last und kann sich besser auf das Wesentliche konzentrieren.
Konventionen in der technischen Dokumentation gibt es in unterschiedlicher Ausprägung, etwa als umfassenden Style Guide ( Google developer documentation style guide, Microsoft writing style guide) oder als schlankes Regelwerk ( AWS document conventions).
Sie brauchen keinen perfekten Style Guide, bevor Sie mit der Dokumentation beginnen. Effektiver ist es, ihn parallel zur Einarbeitung in das Produkt aufzubauen — also während des Onboardings.
Folgende Schritte bieten sich in dieser Phase an:
- Klären Sie beim grundlegenden Aufräumen die Basics:
- Werden Überschriften und Titel im Sentence Case oder Title Case geschrieben? Verwenden sie das Gerundium (-ing-Form) oder die Grundform des Verbs?
- Werden Anleitungen als nummerierte Aufzählungen oder als längerer Fließtext verfasst?
- Gibt es eine strikte Regel zum Oxford-Komma (ein dankbares Thema, wenn Sie eine Debatte unter Autoren entfachen wollen)?
- Wie werden UI-Interaktionen beschrieben — "klickt", "wählt" oder "selektiert" der Nutzer eine Schaltfläche?
- Wie werden Screenshots aufgenommen und dargestellt? Mit Callouts?
- Bauen Sie Ihren internen Style Guide nebenbei auf:
- Picken Sie sich die Rosinen aus den Branchenstandards und passen Sie sie an Ihre Bedürfnisse an.
- Verstehen Sie ihn als lebendiges Dokument, das mit neuer Verwendung und neuer Terminologie wächst.
Ein interner Style Guide ist ein fundamentaler Bestandteil technischer Dokumentation. Er hilft nicht nur dabei, das Autorenteam zu skalieren, sondern gibt auch allen anderen in der Organisation Orientierung, die technische Inhalte verfassen — sei es ein Entwurf für Technical Writer oder ein Blogbeitrag.
Auf dem Weg dorthin stoßen Sie womöglich auch auf grundsätzlichere Fragen, zum Beispiel:
- Wie umgangssprachlich oder persönlich ist der Gesamtstil?
- Wie werden Videos eingesetzt?
- Wie wird mit sensiblen Informationen umgegangen?
- Wer sind die Stakeholder oder aktiven Mitwirkenden an der technischen Dokumentation?
Lassen Sie sich von Ihren Erkenntnissen nicht überraschen.
Die Gestaltung technischer Dokumentation
Technologieprodukte sind komplex. Sie nutzen nicht nur anspruchsvolle Technologien, sondern interagieren auch mit anderen Produkten — oft von anderen Anbietern.
Wie geht man mit dieser Komplexität in der technischen Dokumentation um?
Eine häufige Antwort beginnt mit: "Es kommt darauf an." Trotzdem stehen uns zwei wirkungsvolle Werkzeuge zur Verfügung: das Framework und das konzeptionelle Modell.
Framework
Ein Framework in der technischen Dokumentation kann eine Vorlage oder konzeptionelle Struktur sein, die das Verfassen einzelner Themen erleichtert (also Themen, die nicht mit anderen verknüpft sind).
Die meisten Blogbeiträge und einzelnen Seiten technischer Dokumentation konzentrieren sich auf solche Einzelthemen und profitieren daher von einer klar definierten Vorlage oder einem Framework.
Wollen Sie eine Installationsanleitung schreiben?
Denken Sie an eine dreiteilige Struktur: Voraussetzungen (inklusive Hardware- und Softwareanforderungen), Ausführung (die eigentlichen Installationsschritte) und Verifizierung (Version prüfen, ein Hello-World-Beispiel ausführen usw.).
Stellen Sie eine Anleitung zum Abfragen von Daten zusammen?
Achten Sie darauf, die nötigen Berechtigungen, Beispiel-Queries sowie eine ausführliche Erklärung von Eingabe und Ausgabe einzubinden.
Auch ohne fertige Vorlage können Sie mit etwas Übung relativ leicht ein eigenes Framework entwickeln. Bevor ich zu DoiT kam, habe ich einen Blogbeitrag mit dem Titel How to write (and rewrite) verfasst. Der dort vorgeschlagene Ansatz dreht sich im Kern um den Aufbau eines solchen Frameworks.
Hier die Kernpunkte:
- Nutzen Sie das Minto Pyramid Principle®, um die zugrunde liegende Struktur eines komplexen Textes sichtbar zu machen
- Schaffen Sie visuelle Hierarchien, die der Leserschaft helfen, sich im Komplexen zurechtzufinden
- Bilden Sie sinnvolle Cluster, die die User Journey unterstützen
Konzeptionelles Modell
Die Komplexität von Technologieprodukten entsteht zum großen Teil durch Interaktionen — entweder zwischen Komponenten desselben Produkts oder zwischen Produkten innerhalb derselben Geschäfts- bzw. Technologielandschaft, die zusammenspielen müssen, um eine vollständige Lösung zu bilden.
Die produktinterne Komplexität legen Sie in der Regel nicht offen. Ihre Geheimrezeptur mag für Wettbewerber spannend sein, für Ihre Kunden ist sie es nicht zwingend.
Sehr wohl beachten sollten Sie aber jene Komplexitäten, die zu externer Reibung führen können. Sie sind häufig der Grund, warum Kunden — und sogar das eigene Support-Team — ins Stocken geraten.
In seinem viel beachteten Buch The Design of Everyday Things erklärt Donald Norman, dass ein gutes konzeptionelles Modell das wichtigste Prinzip zur Bändigung von Komplexität ist. Dem stimme ich uneingeschränkt zu.
Schauen wir uns anhand zweier Beispiele aus dem DoiT Help Center genauer an, wie sich konzeptionelle Modelle in der technischen Dokumentation nutzen lassen.
Building-Block-Features
Über das Attributions-Feature sagt DoiT Product Marketing Manager Matan Bordo gerne, es sei "eines der bindungsstärksten Features von DoiT Cloud Intelligence™, wenn man es richtig einsetzt". Wenn Sie daraus schließen, dass es nicht ganz einfach ist, das volle Potenzial dieses Features auszuschöpfen — wir verstehen Sie.
Attributions ist ein Building-Block-Feature. Wie viele andere Bausteine erreicht es für sich genommen wenig. Hat man jedoch sein Wesen erfasst, macht die Arbeit damit richtig Spaß.
In einem aktuellen Update haben wir die Dokumentation überarbeitet und die Anwendungsszenarien an den Anfang gestellt — damit Nutzer zuerst verstehen, was das Feature leistet, bevor sie sich in die Konfigurationsdetails vertiefen.
Ecosystem-Plugin-Features
Im September haben wir den Artikel Visualize with Grafana Cloud ergänzt (beigetragen von unserem CTO und Mitgründer Vadim Solovey). Wie Sie vielleicht wissen, ist Grafana keine Lösung von DoiT, sondern ein verbreiteter Service in der Cloud Native Landscape.
Ähnlich wie beim Building-Block-Beispiel haben wir in der Einleitung den Sinn der Integration dargelegt — und aufgezeigt, in welcher Hinsicht sie einem Cloud-Geschäft Vorteile bringt.
Ob im Produkt oder im Ökosystem: Ein gutes konzeptionelles Modell zeichnet das Zusammenspiel der Komponenten nach und hilft Nutzern, sich in der gewählten Domäne zurechtzufinden.
Weitere Vorteile? Eines ist bei Technologie sicher: Nutzer sind kreativ, wenn es darum geht, mit Technologie ihre Probleme zu lösen. Mit einem stimmigen konzeptionellen Modell entdecken Ihre Nutzer neue Use Cases für Ihr Produkt — und werden, noch besser, zu freiwilligen Evangelisten, die Ihnen helfen, sich weiter zu verbessern.
Es ist Teamarbeit
Wo stehen wir also?
Konventionen und Frameworks lassen sich mit allgemeinem Technical-Writing-Wissen handhaben (und sind daher ein guter Einstieg für neue oder noch unerfahrene Autoren). Der Aufbau passender konzeptioneller Modelle auf verschiedenen Ebenen erfordert dagegen tiefes Produktwissen.
DoiT ist ein Technologieunternehmen, das stolz auf seine ausgewiesene Cloud-Expertise und seine kundenzentrierte Haltung ist. Die Lernumgebung ist hervorragend. Themen, die in internen Slack-Channels diskutiert und im internen Wiki oder auf StackOverflow geteilt werden, stecken voller Wissen — und die Menschen hier teilen ihr Know-how gerne, helfen einander und arbeiten zusammen, um sich individuell und gemeinsam weiterzuentwickeln.
Als Teil des interdisziplinären Produktmanagement-Teams sind Technical Writer Sparringspartner für Product Manager und Designer. Klar zu schreiben setzt klares Denken voraus — und das ist enorm wertvoll, wenn es darum geht, Annahmen sichtbar zu machen und Produktfeatures zu modellieren.
Bei der Diskussion darüber, was das Technical-Writing-Team erreichen will, haben wir uns vorgenommen, technische Dokumentation zu einem wertvollen Asset im DoiT-Produktportfolio zu machen. Der Schlüssel dazu ist Teamarbeit. Hochwertige technische Dokumentation ist keine Einzelkämpfer-Aufgabe für Technical Writer, sondern ein Vorhaben, bei dem das Technical-Writing-Team von DoiT die Federführung übernimmt und eng mit der gesamten Organisation zusammenarbeitet.