Strategien zum Schreiben effektiver technischer Dokumentation

Seit 1999, als ich für die Qualitätssicherung für die F&E-Niederlassung von Altec Lansing in Kfar Saba, Israel, zuständig war, beschäftige ich mich mit technischen Texten der einen oder anderen Art. Damals brachten wir innovative, audiobezogene Geräte wie (keuch) USB-Audiogeräte auf den Markt, die unter Windows ME und 2000 funktionierten. Sie waren fehlerhaft und ihre Einrichtung war nicht mehr so einfach wie heute.

Wir brauchten Dokumente.

Wir hatten einige Hürden, die die Benutzer überwinden mussten, und wir brauchten eine Möglichkeit, zu dokumentieren, was das war, was die Randfälle waren und wie man all diese Probleme diagnostizieren und beheben konnte. Es musste gut verpackt, sauber formatiert und für Benutzer zugänglich sein, die unsere Hilfsanwendung installiert hatten. Ich habe die Robohelp-Anwendung gefunden, die zum Erstellen von Standard-Hilfeanwendungen unter Windows verwendet wird, und unserer Installation eine Hilfedatei hinzugefügt.

Während unseres Qualitätssicherungsprozesses identifizierten wir die Probleme, dokumentierten, was unserer Meinung nach wichtig war, und organisierten es in der Hilfedatei, die mit dem Gerät geliefert wurde. Ich war damals 19 und hatte keinerlei Erfahrung mit diesem Zeug, und es war ein äußerst naiver Prozess. Nichtsdestotrotz fühlte es sich für unsere Benutzer einfach wie das Richtige an, und mein Vorgesetzter hat mir nicht ausdrücklich gesagt, dass ich das nicht tun soll.

Es ist 24 Jahre her und seitdem habe ich Dokumentationen für eine Reihe von Projekten erstellt. Der Umfang ist gewachsen und die Art und Weise, wie ich diese Art von Projekten betrachte, hat sich grundlegend verändert.

Ich habe einige Gedanken darüber, was gute Dokumente ausmacht, und ich würde sie gerne mit Ihnen teilen, wenn Sie interessiert sind.

Kernkonzept der Dokumentation

Ich möchte mit einer Reihe konkreterer Regeln beginnen, die meiner Meinung nach für den Erfolg eines Dokumentationsprodukts entscheidend sind.

• Dokumente sollten kleine Wörter verwenden, um große Ideen zu beschreiben – verwenden Sie also keine überschwänglichen Wörter oder komplexen Sätze, um das, was in einfacheren Worten gesagt werden kann, zu beschreiben. Sie werden unterwegs Benutzer verlieren und es ist das Ego Ihres Autors nicht wert.

• Dokumente sollten, wenn möglich, eine Geschichte erzählen – denn ein persönlicher, nachvollziehbarer Satz von Aufgaben, die eine Geschichte erzählen, wird für Ihren Benutzer ansprechender und einprägsamer sein als ein abstrakter Satz von Anweisungen.

• Dokumente sollten durchsuchbar sein – denn im Ernst: Das ist ein Kinderspiel. Wenn Ihre Dokumente nicht leicht zu finden sind, werden Ihre Benutzer nicht finden, was sie brauchen.

• Dokumente sind fast immer Teil einer größeren Strategie – und das gilt insbesondere, wenn es um Softwareprodukte geht. Dies berührt das größere Thema der Interessenvertretung von Entwicklern, aber kurz gesagt: Ihre Dokumente sollten durch Video-Tutorials, reale Anwendungsbeispiele und technischen Live-Support unterstützt werden.

• Dokumente sollten getestet werden – denn Sie können sicher sein, dass alles stimmt, aber ohne echte Benutzer, wie bei jedem anderen Produkt, werden Sie es nicht sicher wissen. Testen Sie es und testen Sie es erneut.

  
  

Ganzheitliche Dokumente sind gut gestaltete Produkte

Wenn Sie eine neue Programmiersprache lernen, fließen Konzepte und Ideen aus dieser Sprache in Ihre Trickkiste zur Problemlösung ein. Es macht Sie zu einem besseren Softwareentwickler und am Ende des Tages machen Sie bessere Software, weil Sie bewusster und fähiger sind.

Meine Karriere war kompliziert und umfasste viel Softwareproduktdesign, Softwareentwicklung, technischen Support und die Interessenvertretung von Entwicklern. Jede Disziplin hat mein Denken und meinen Umgang mit anderen beeinflusst.

Wenn ich an ein technisches Schreibprojekt herangehe, geschieht dies mit dieser umfassenden Sicht auf das, was ein Benutzer benötigen wird. Ich denke, das ist die richtige Art, über Dokumente nachzudenken: ganzheitlich. Dokumente sind keine genau definierte Sache und um gute Dokumente zu erstellen, muss man flexibel sein.

Für mich bedeutet das, dass man seine Nutzer aus möglichst vielen Blickwinkeln betrachten muss. Sie können nichts als selbstverständlich betrachten, sonst lassen Sie eine Gruppe von Benutzern auf eine Art und Weise im Stich, die sich negativ auf Ihre Marke, Ihr Produkt oder Ihr Unternehmen auswirkt und von der Sie nur schwer wiederkommen können.

Ihre Dokumente sind für Ihre Benutzer oft ein entscheidendes Erlebnis.

Wenn Sie gute Arbeit leisten, werden Ihre Benutzer Ihr Produkt erfolgreich nutzen und zu Champions Ihrer Marke werden. Wenn Sie dies nicht tun, werden sie Ihr Produkt wahrscheinlich nie wieder verwenden, weil Ihre Dokumente einen schlechten Geschmack in ihrem Gedächtnis hinterlassen haben. Sie werden es auch anderen mitteilen. Gutes Marketing beginnt hier, also denken Sie daran.

Gute Dokumente erstellen

Gute Dokumente zu erstellen bedeutet einfach, dass Sie bei der Erstellung Ihrer Dokumente wie bei jedem anderen Produktprozess vorgehen müssen.

Du brauchst:

• Erfahren Sie, warum Sie Ihre Dokumente erstellen
• Wissen Sie, wer Ihre Zielgruppe ist
• Wissen Sie, was ihre Schmerzpunkte sind
• Verbessern Sie Ihre Dokumente im Laufe der Zeit

Schauen wir uns die einzelnen Punkte genauer an.

Das Warum Ihrer Dokumente zu kennen, ist oft eine oberflächlich betrachtet sehr einfache Frage und Antwort. Sie erstellen Dokumente, denn wenn Sie dies nicht tun, werden Benutzer durchs Raster fallen und Ihr Produkt nicht verwenden. Auf einer tieferen Ebene gibt es eine spezifische Antwort für Ihren Anwendungsfall. Haben Sie ein Entwicklertool? Das ist ein Antwortsatz. Haben Sie ein Einzelhandelsdesign-Tool? Besitzen Sie ein Buchhaltungs-SaaS-Produkt? Besitzen Sie eine automatische Kaffeemaschine? Dies sind alles separate Antwortsätze.

Die Form Ihrer Dokumente wird dadurch beschrieben, wer sie verwenden wird. Ist es online? Ist es mit einer App gebündelt? Ist es gedruckt? Jede Benutzerbasis benötigt etwas anderes, und Sie müssen von Anfang an klar sein, wer sie sind.

Ihre Aufgabe besteht darin, herauszufinden, was für jeden Ihrer Benutzer schwierig ist, und Ihre Dokumente so zu gestalten, dass sie ihnen informative Inhalte vermitteln, die ihr spezifisches Problem lösen.

Am wichtigsten ist, dass Sie wissen, dass Sie es wahrscheinlich nicht beim ersten Mal richtig machen werden. Das bedeutet, dass Ihre Dokumente gepflegt und aktualisiert werden müssen, wenn Ihre Produkte im Laufe der Zeit wachsen und sich ändern. Hoffentlich geschieht dies in einem Rahmen, der eine einfache Kommunikation mit den Benutzern ermöglicht, denen Sie helfen möchten. Sie müssen mit Ihren Benutzern sprechen, auf ihre Bedürfnisse hören und versuchen, Ihre Dokumente zu nutzen, um ihre Erfahrungen mit Ihrem Produkt zu verbessern.

Ihre Dokumente sind ein wesentlicher Bestandteil Ihres Erfolgs

Ich fasse zusammen, indem ich einfach unterstreiche, wie wichtig Dokumente sind. Ohne sie sind Ihre Benutzer auf sich allein gestellt und müssen für sich selbst sorgen.

Dies bedeutet immer weniger Erfolgsfälle, eine schlechtere Sicht auf Ihr Produkt in Ihrem Ökosystem, mehr unzufriedene Entwickler oder Benutzer und negative Auswirkungen auf Ihre Marke oder Ihr Unternehmen.

Dokumente sind ein eigenständiges Unterprodukt, eine Investition und müssen Teil Ihrer umfassenderen Produktstrategie sein.