Was ist technisches Schreiben?

Sie haben bereits fünf Stunden damit verbracht, Ihre WordPress-Seite einzurichten. Aber Sie konnten die Nadel nicht bewegen.

Wenige Stunden später, müde, erkunden Sie zufällig die WordPress-Dokumentation – Ihren unbesungenen Helden.

Sie haben das Hilfezentrum durchgesehen, die FAQs und Installationsanleitungen gelesen. Und voilà, innerhalb der nächsten Stunden haben Sie eine einfache Wordpress-Seite veröffentlicht.

Dank der technischen Dokumentation auf der Website. Sie hat Ihnen Zeit und die Kopfschmerzen erspart, in denen Sie sonst ertrunken wären.

Genau wie WordPress hat fast jede Software eine technische Dokumentation, die auf ihrer Website geschrieben und veröffentlicht wird. Warum? Um die Benutzererfahrung reibungsloser zu gestalten.

In diesem Artikel werden wir alles über technisches Schreiben erzählen und wie Sie Ihre erste technische Dokumentation erstellen können.

Legen wir los.

Was technisches Schreiben wirklich ist?

Technisches Schreiben ist eine spezialisierte, benutzerorientierte Form des Schreibens, die komplexe, technische Themen in eine leicht verdauliche und verständliche Sprache vereinfacht.

Das Ziel des technischen Schreibens ist einfach: Leser dazu bringen, den Anweisungen zu folgen.

Denken Sie an: Benutzerhandbücher, Anleitungen zur Installation einer App oder Software, Produktspezifikationen technischer Software, Standardarbeitsanweisungen (SOPs) usw.

Wenn Sie beispielsweise Microsoft Office in Ihrem System installieren möchten, aber keine klaren Anweisungen haben, wie das geht.

Sie laden die Installationsanleitung von Microsoft herunter, in der alle Schritte zur Installation der Software auf Ihrem Computer detailliert beschrieben sind.

Es werden alle Schritte aufgelistet – vom Herunterladen der Software über das Ausführen bis hin zum Befolgen der Anweisungen.

Arten des technischen Schreibens

Technisches Schreiben verzweigt sich in fünf verschiedene Kategorien, die Sie kennen sollten.

• Endbenutzerdokumentation: Sie schult den Benutzer eines Produkts über die Kernfunktionalität des Produkts und wie er häufige Fehlerbehebungsprobleme lösen kann. Zum Beispiel Benutzerhandbücher, Installationsanleitungen, Hilfezentren, FAQs und Wissensdatenbanken.
• Prozessdokumentationsschreiben: Diese Art des technischen Schreibens konzentriert sich auf die Standardisierung von Verfahren innerhalb des Unternehmens und ist speziell für interne Teams konzipiert. Zum Beispiel Standardarbeitsanweisungen (SOPs) und interne Wikis.
• Technische Marketingkommunikation: Sie nutzt technisches Fachwissen und Marketingstrategien zusammen, um den Wert komplexer Produkte zu vermitteln. Zum Beispiel Fallstudien, Landing Pages und Business-E-Mails.
• Experte-zu-Experte-Technisches Schreiben: Es ist nischenorientiert und bietet Experteninformationen für Personen, die bereits Experten auf ihrem Gebiet sind. Der Haken? Diese Art des Schreibens kann nur von technischen Redakteuren oder Personen geschrieben werden, die über spezielle Kenntnisse verfügen oder Experten auf ihrem Gebiet sind. Zum Beispiel Whitepapers und Forschungszusammenfassungen.
• Technische Berichte: Diese Art des Schreibens präsentiert detaillierte Informationen über Forschungsergebnisse, Projektergebnisse oder technische Analysen. Zum Beispiel Forschungsberichte, Fortschrittsberichte, technische Vorschläge und Machbarkeitsstudien.

Lesen Sie auch: Was ist Engineering-Dokumentation?

Beispiele für technisches Schreiben

Aber wie genau sieht technisches Schreiben aus? Sehen wir uns ein paar Beispiele für technisches Schreiben an, um es besser zu verstehen.

Produktdokumentation

Eine Produktdokumentation enthält detaillierte Informationen zu den technischen Spezifikationen des Produkts, seinen Funktionen, Schritt-für-Schritt-Anleitungen für den Einstieg in das Produkt und umfassende Handbücher zur Verwendung des Produkts.

Sie enthält in der Regel Systemspezifikationen für Benutzer zum Ausführen der Software, Installations- und Gebrauchsanweisungen, FAQs oder eine Wissensdatenbank.

Agorapulse zum Beispiel hat eine saubere und minimale Produktdokumentation auf seiner Website.

Wenn Sie auf den jeweiligen Block klicken, sagen wir „Erste Schritte“, sehen Sie die verschiedenen verlinkten Fragen zu Tipps zur Fehlerbehebung und funktionsspezifischen Informationen.

Lesen Sie auch: Das Dokumentationssystem, das Agorapulse antreibt

API-Dokumentation

Die API-Dokumentation ist eine Sammlung von Anweisungen, die erklären, wie Entwickler mit Softwareanwendungen interagieren. Diese Dokumentation enthält detaillierte Informationen über die Endpunkte der API, Codebeispiele und Authentifizierungsmethoden.

Zum Beispiel Kit API-Dokumentation eine kurze Übersicht und Abschnitte wie Änderungen, Authentifizierung, OAuth, API-Schlüssel und mehr.

Standardarbeitsanweisungen (SOPs)

SOPs sind wie GPS für Teams – sie bieten klare Anweisungen, die Teammitgliedern helfen zu verstehen, wie sie eine bestimmte Aufgabe innerhalb eines Unternehmens erledigen können.

Hier ist ein Beispiel dafür, wie eine Mitarbeiter-Onboarding-SOP aussieht:

Versionshinweise

Versionshinweise informieren Benutzer über neue Produktfunktionen, Verbesserungen und Fehlerbehebungen in Software-Updates.

Zum BeispielWix die Versionshinweise auf ihrer Website veröffentlicht. Jede Versionshinweis hat ein Datum und ist kurz in Stichpunkten strukturiert. Das Beste daran? Jedes Update ist mit spezifischen technischen Dokumentationsanweisungen verlinkt.

Prinzipien des technischen Schreibens

Nachdem Sie nun die verschiedenen Variationen des technischen Schreibens kennen, wollen wir die fünf Kernprinzipien des technischen Schreibens verstehen.

Jeder Inhaltstyp wird basierend auf diesen Prinzipien geschrieben.

Klarheit und Präzision

Beim Lesen technischer Dokumentation haben die Leser ein Ziel: schnell die Informationen finden und umsetzen.

Sie können dieses Ziel für Leser, die die technische Dokumentation lesen, nur erreichen, indem Sie eines tun: klar und prägnant schreiben.

Und wie geht das?

• Halten Sie Ihr Schreiben klar und auf den Punkt.
• Geben Sie bei Bedarf Definitionen für Fachbegriffe an
• Entfernen Sie Fachjargon aus Ihrem Schreiben – Wörter, die die Lesbarkeit beeinträchtigen, wie z. B. „nur“, „das“, „sehr“ usw.

Hier ist ein Beispiel für schlecht geschriebene technische Dokumentation.

Bildquelle

So würde es aussehen, wenn es zur besseren Verständlichkeit verbessert würde:

Sehen Sie den Unterschied? Das Lesen der ersten Dokumentation macht es dem Leser schwer, die Informationen zu erfassen.

Aber die verbesserte Version? Sie vereinfacht die Informationen und ist in weniger Worten und so geschrieben, dass der Leser sie aufnehmen und umsetzen kann.

Genau so müssen Sie Ihre Dokumentation schreiben, um Klarheit zu schaffen.

Gründlichkeit

Um den Lesern zu helfen, ihr Ziel zu erreichen – ein Problem in der App zu beheben oder die DIY-Möbel zu bauen – müssen Sie jedes kleinste Detail einbeziehen, um den Lesern zu helfen, die Anweisungen Schritt für Schritt zu befolgen.

Dies bedeutet, die Dokumentation mit jedem Detail mit Diagrammen, Flussdiagrammen, Visualisierungen, Code und Videos zu versehen, um die Informationen zu vereinfachen und sie für den Leser umsetzbar zu machen.

Wie hierStorylane jeden Mikroschritt ab, um den Benutzern zu helfen, loszulegen und ihre erste Demo auf der Plattform zu erstellen.

Logische Struktur

Um dem Leser zu helfen, von Punkt A nach B zu gelangen und das gewünschte Ergebnis zu erzielen, müssen Sie Ihre Dokumente gut strukturieren. Denken Sie an: eine Reihe von aussagekräftigen Abschnitten, Überschriften, Titeln und Anleitungen.

Lassen Sie uns dies anhand eines Beispiels besser verstehen.

Ein Benutzerhandbuch beginnt mit einer Anleitung zur Fehlerbehebung, springt dann zu Installationsanweisungen, gefolgt von einem Abschnitt über Funktionen und endet mit Glossarbegriffen.

Sehen Sie das Problem? Benutzer werden Informationen lesen, die sie im Moment nicht benötigen. Und die Informationen, die sie brauchten? Diese Information ist unter fortgeschrittenen Themen vergraben.

Deshalb müssen Sie logisch darüber nachdenken und die Dokumentation benutzerorientiert gestalten, indem Sie die Informationen in logischen Reihenfolgen einfügen.

Faktische Richtigkeit

Im Gegensatz zu anderen Formen des Schreibens, bei denen man persönliche Meinungen, Anekdoten und Geschichten hinzufügen kann, erfordert technisches Schreiben Fakten, Wissen und Recherche.

Die technische Dokumentation sollte sich auf Fakten konzentrieren und erklären, was ein Produkt tut, für wen es bestimmt ist und welchen Wert es bietet.

Zum BeispielSlacks Dokumentation nicht, dass sie das beste Collaboration-Tool sind. Aber es stellt sich subtil vor und geht direkt auf die Agenda des Dokuments ein – wie man mit Slack beginnt und welche verschiedenen Elemente der Benutzer in Aktion innerhalb des Tools sehen wird.

Problemlösung

Jede technische Dokumentation sollte ein Ziel haben: das Problem des Benutzers zu lösen.

Dazu müssen Sie zunächst das Problem identifizieren, das Sie mit der Dokumentation lösen. Schreiben Sie dann die genaue Lösung auf, die ihnen helfen würde. Um die Lösung besser zu erklären, können Sie auch Beispiele, kommentierte Screenshots und Video-Tutorials einfügen.

Slite verwendet eine Mischung aus Loom-Videos und Produkt-Screenshots, wenn es spezifische Anweisungen gibt.

In ihrem Abschnitt „So richten Sie Ihren Arbeitsbereich ein“ sehen Sie beispielsweise, dass das Dokument alle Funktionen aufgelistet hat, mit denen der Benutzer vertraut sein muss. Für mehr Klarheit wird ein Produkt-Screenshot hinzugefügt, um die Anweisungen klarer zu machen.

Der technische Schreibprozess

Der große Elefant im Raum: Wie schreibt man *eigentlich* eine technische Dokumentation? Das Schreiben technischer Dokumentation durchläuft verschiedene Phasen: Planung, Recherche, Schreiben und Bearbeiten und schließlich Veröffentlichung.

Lassen Sie uns jede Phase im Detail verstehen.

Phase 0: Planung

Kennen Sie zunächst, für wen Sie die Dokumentation schreiben – Entwickler, Systemadministratoren oder Benutzer? Identifizieren Sie nun, wer das Dokument verwenden wird und welche Informationen er suchen wird.

Fragen Sie sich dann:

• Was ist das Hauptziel, das Leser nach dem Lesen dieser Dokumentation erreichen wollen?
• Schreiben Sie für Experten oder ein allgemeines Publikum?
• Welche Informationen wird diese Dokumentation abdecken?

Phase 1: Recherche

Sammeln Sie schließlich die notwendigen technischen Details – Produktspezifikationen, Designdokumente, vorhandene Dokumentation und Erkenntnisse von Fachexperten.

Erstellen Sie einen Fragebogen

Beschreiben Sie eine neue Funktion der App? Um darüber zu schreiben, muss der technische Redakteur die Vor- und Nachteile der Produktfunktion verstehen.

Einige Fragen, die ein ausgezeichneter Ausgangspunkt sein könnten, sind:

• Ist dies eine neue Funktion oder eine verbesserte Version der älteren Funktion?
• Was macht sie und wie können Benutzer sie verwenden?
• Welche Themen verweisen auf diese Funktion?
• Gibt es Hinweise/Warnungen, die in die Funktionsbeschreibung aufgenommen werden müssen?
• Benötigen Sie Screenshots, GIFs, Diagramme oder Videos, um die Informationen besser darzustellen?

Identifizieren Sie glaubwürdige Quellen

Finden Sie die Quellen mit sachlich korrekten und aktuellen Informationen. Es gibt zwei glaubwürdige Quellen, die Sie zum Schreiben Ihrer Dokumentation verwenden können:

Produkt

Wenn Sie eine Funktionsdokumentation schreiben, probieren Sie die Funktion selbst aus und dokumentieren Sie den genauen Schritt-für-Schritt-Prozess.

Auf diese Weise erhalten Sie aus erster Hand Erfahrungen mit dem Produkt und verstehen klar, wie das Produkt funktioniert – von Schritt 1 bis Schritt N – und helfen Ihnen, genaue Anweisungen zu schreiben.

Fachexperten (SMEs)

Interviewen Sie die internen SMEs – Experten aus den Produkt- oder Engineering-Teams – um Erkenntnisse zu gewinnen, wenn Sie explizit über das Produkt schreiben.

Dies hilft Ihnen, Erkenntnisse direkt von der Person zu erhalten, die eng mit dem Produkt zusammengearbeitet hat, und diese wird über umfassende Erkenntnisse verfügen.

Bildquelle

Aber die eigentliche Frage für technische Redakteure ist: „Wie interviewe ich KMUs?“

Ganz einfach. Stellen Sie den KMUs offene Fragen, die sich speziell auf die Informationen beziehen, die Sie benötigen. Nehmen wir an, Sie schreiben eine Feature-Dokumentation, dann könnten Sie Fragen stellen wie:

• Können Sie mir den Prozess der Nutzung dieser Funktion demonstrieren?
• Benötigen Sie während dieses Schritts erhöhte Berechtigungen?
• Wie kann dieser Prozess erkannt werden, wenn er fehlschlägt, und wie kann er eskaliert werden?

Erfassen Sie so viele Erkenntnisse wie möglich von den KMUs in einem Interview. Wenn es jedoch erforderlich ist, wenden Sie sich in einem weiteren Gespräch an die KMUs und klären Sie Ihre Zweifel.

💡Profi-Tipp:

• Verwenden Sie Videoaufzeichnungstools, um das KMU-Interview aufzuzeichnen und die Aufzeichnung dann zum Schreiben Ihrer Dokumentation zu verwenden.
• Anstatt die gesamte Recherche auf Google Docs zu verteilen, verwenden Sie Tools für die Zusammenarbeit an Dokumenten wie Slite, um alles an einem Ort zu organisieren – aufgezeichnete Videos, Ressourcenlinks usw.

Phase 2: Inhaltsorganisation

Mit der Recherche fertig? Organisieren Sie alle Informationen in einem Dokument und entwerfen Sie die Gliederung.

Strukturieren Sie Ihre Dokumentation dazu aus der Perspektive des Benutzers – was möchte er zuerst lesen?

Denken Sie darüber nach und strukturieren Sie Ihre Überschriften und Unterüberschriften entsprechend.

Beginnen Sie beispielsweise mit den allgemeinen Informationen und gehen Sie dann zu speziellen Funktionen über.

Genau so hat es die API-Dokumentation von Reddit gemacht. Sie deckt alle API-Elemente in der gesamten Dokumentation ab.

Das Dokument beginnt mit allgemeinen Informationen und verzweigt sich dann in spezifische API-Funktionen, die Benutzer für ihre Bedürfnisse durchsuchen können. Jede Funktion enthält eine Beschreibung, eine Methode, ein Codebeispiel und Parameter.

In Anbetracht der Art und Weise, wie Reddit seine Dokumentation geschrieben hat, können Sie eine Gliederung mit klaren Überschriften und Unterüberschriften erstellen. Hier ist eine Beispielgliederung, die Sie als Ausgangspunkt verwenden können:

Phase 3: Schreiben und Bearbeiten

Nachdem Sie nun eine strukturierte Gliederung haben, ist es an der Zeit, zum nächsten Schritt überzugehen: das Schreiben der technischen Dokumentation. Wie geht man das an?

Beginnen Sie damit, die Gliederung mit den Informationen zu füllen, die Sie während des Rechercheprozesses gesammelt haben.

Nehmen wir an, Sie arbeiten an dem Abschnitt „Authentifizierung“ aus der Beispielgliederung. Hier fügen Sie alle Informationen hinzu, die Sie im KMU-Interview gesammelt haben.

Aber das ist noch nicht alles, um Ihre technische Dokumentation zu schreiben. Hier sind ein paar Möglichkeiten, um sie hervorzuheben:

• Decken Sie die Informationen Schritt für Schritt ab: Erläutern Sie jeden Schritt im Detail, damit die Benutzer wissen, wie sie jeden Schritt abschließen und zum nächsten Schritt übergehen können, ohne beim Befolgen der Anweisungen einen Fehler zu machen.
• Schreiben Sie in prägnanter Sprache: Halten Sie die Sprache einfach und prägnant, ohne zu viel technisches (und irrelevantes) Fachjargon und komplexe Formulierungen hinzuzufügen.
• Formatieren Sie für Lesbarkeit: Stellen Sie sicher, dass Sie den Text in Absätze unterteilen, die Verlinkung formatieren und die Informationen mithilfe visueller Elemente wie Videos, Screenshots und GIFs gut darstellen.

Sobald Sie Ihren ersten Entwurf geschrieben haben, ist es an der Zeit, die Bearbeitungsprüfungen durchzuführen.

Konzentrieren Sie sich bei der Bearbeitung auf zwei Arten der Bearbeitung:

Schritt 1: Entwicklungsredaktion

Die Entwicklungsredaktion zielt darauf ab, die Dokumentation effektiver zu gestalten, während sie auf der Grundlage von Informationen und Relevanz für die Zielgruppe bewertet wird.

Überprüfen Sie den Entwurf auf Struktur und Inhalt und bewerten Sie den logischen Fluss von Ideen, die Relevanz der Informationen und die Ausrichtung auf die Zielgruppe.

Schritt 2: Stilredaktion

Sobald Sie die Entwicklungsredaktion abgeschlossen haben, ist es an der Zeit, die Sätze zu verfeinern.

Achten Sie dabei auf die Satzstruktur, die Wortwahl, die narrative Kohärenz und den Schreibstil. Konzentrieren Sie sich auch auf den Schreibstil und die Sprache, um sicherzustellen, dass jeder Satz die Informationen klar vermittelt.

Schritt 3: Korrekturlesen

Überprüfen Sie nun die Dokumentation auf technische Richtigkeit – Rechtschreibfehler, Zeichensetzung, Faktenprüfung und Stilrichtlinien.

Möchten Sie Ihren Korrekturleseprozess beschleunigen? Verwenden Sie Tools wie Grammarly und Hemmingway.

Phase 4: Überprüfung und Feedback

Sobald Sie das Dokument geschrieben und bearbeitet haben, ist es an der Zeit, es an KMUs zu senden, um deren Feedback zu erhalten und die notwendigen Änderungen vorzunehmen. Wie geht das?

• Teilen Sie den Entwurf in einem Tool für die Zusammenarbeit an Dokumenten wie Slite und laden Sie die KMUs ein, an dem Dokument mitzuarbeiten.
• Bitten Sie die KMUs, ihr Feedback zu Parametern wie Fachwissen, benutzerspezifischen Informationen, die übersehen wurden, und der Relevanz der Dokumentation für die Benutzer zu geben.
• Die KMUs können die Teile des Dokuments hervorheben, in denen sie weitere Erkenntnisse hinzufügen möchten, und ihre Kommentare hinzufügen.

Anstatt die KMUs immer wieder zu kontaktieren und sich mit ihnen zu einem Gespräch zu treffen, um Feedback zu erhalten und Punkte zu klären, beschleunigt diese Form der Zusammenarbeit den Feedbackprozess. Eine Win-Win-Situation für die technischen Redakteure und KMUs.

Phase 5: Veröffentlichung und Wartung

Und hier kommt nach all der harten Arbeit der letzte Schritt – die Veröffentlichung Ihrer Dokumentation.

Wählen Sie für diesen letzten Schritt die richtige Veröffentlichungsplattform, um Ihre Dokumentation live zu schalten.

Hier sind fünf Optionen, aus denen Sie wählen können:

• Erstellen der Dokumentationswebsite
• Veröffentlichen der Dokumente auf GitHub
• Verwenden eines Veröffentlichungstools
• Freigabe über Cloud-Ordner
• Starten einer Hilfecenter-Seite auf Ihrer Website

Von diesen sind die Verwendung eines Veröffentlichungstools und das Starten der Hilfecenter-Seite die besten Möglichkeiten, das Dokument zu veröffentlichen.

• Wenn Sie Benutzerdokumentation erstellen möchten, starten Sie die Hilfecenter-Seite auf Ihrer Website.
• Wenn Sie die Dokumentation für Ihr internes Team erstellen möchten, ist die Verwendung eines Veröffentlichungstools wie Slite am besten – es ermöglicht Ihnen sogar, die Dokumentation zu überprüfen und die Informationen auf dem neuesten Stand zu halten.

Tools zur Beschleunigung Ihres technischen Schreibprozesses

• Dokumentationsplattform: Organisieren Sie Ihre Recherche – alle Ideen, Materialien, die Sie gesammelt haben, Videoaufzeichnungen und Transkriptionen, die Sie erfasst haben – in einem zentralen Hub, um alles an einem Ort abzurufen. Es vereinfacht auch die Weitergabe der gesammelten Informationen an Stakeholder und KMUs, mit denen der technische Redakteur zusammenarbeitet. Dieses Tool ist perfekt für Ihre Recherche, Planung und Ihren Schreibprozess.

Beispiel: Google Docs, Notion oder Slite.

• Tools für die Zusammenarbeit: Verzichten Sie auf das Hin und Her, um KMUs zu kontaktieren und tagelang auf deren Genehmigung zu warten. Sie können asynchron mit Tools für die Zusammenarbeit zusammenarbeiten, indem Sie den KMUs und Stakeholdern Nachrichten senden. Dies funktioniert noch besser, wenn die Dokumentationstools über integrierte Funktionen für die Zusammenarbeit oder die Integration mit Plattformen für die Zusammenarbeit verfügen. Diese Tools sind perfekt, wenn Sie Feedback zum ersten Entwurf von KMUs benötigen – Sie können ihnen Folgefragen stellen und die Zweifel klären, ohne die Dokumentation zu verlassen.

Beispiel: Slite und Slack.

• Bearbeitungstool: Haben Sie Ihren ersten technischen Inhalt entworfen? Verwenden Sie Bearbeitungstools, um Ihren Bearbeitungsprozess während der Stilredaktion und des Korrekturlesens zu beschleunigen. Mit solchen Bearbeitungstools können Sie Ihre Inhalte auf Rechtschreibfehler, Zeichensetzung, Satzumformulierungen und Klarheit bearbeiten.

Beispiel: Grammarly, Hemmingway Editor oder Wordtune.

• Designtool: Sobald der Inhalt genehmigt wurde, ist der nächste Schritt das Entwerfen der Visualisierungen. Mit Designtools können Sie alle Visualisierungen erstellen, die Sie in Ihre Dokumentation aufnehmen möchten – Infografiken, Flussdiagramme und GIFs. Diese Tools verfügen auch über vorgefertigte Vorlagen, die Sie verwenden können, anstatt alles von Grund auf neu zu entwerfen.

Beispiel: Canva zum Entwerfen und Zight zum Erstellen von Screenshots und Kommentieren der Produktbildschirme.

• Videoaufzeichnungs- und Transkriptionstool: Während des Rechercheprozesses, wenn Sie Erkenntnisse von KMUs sammeln, sind Videoaufzeichnungs- und Transkriptionstools Ihr Retter. Integrieren Sie diese Tools während des Gesprächs; es zeichnet das Gespräch für Sie auf und liefert sogar eine Transkription des gesamten Gesprächs. Auf diese Weise können sich technische Redakteure darauf konzentrieren, den Erkenntnissen des KMU zuzuhören, ohne abgelenkt zu werden.

Beispiel: Zoom, Fireflies.ai oder Fathom.

• Veröffentlichungstool: Dies ist Ihr Held-Tool zum Veröffentlichen und Verwalten der Inhalte, insbesondere wenn Sie die technischen Inhalte nicht auf Ihrer Website veröffentlichen. Mit diesen Tools können Sie Inhalte veröffentlichen und verschiedene Formatierungsstile einbetten – Tabellen, Datenbanken und Inhalte direkt aus anderen Tools. Am wichtigsten ist, dass Sie Ihre Inhalte aktuell und auf dem neuesten Stand halten können, ohne dies manuell zu tun.

Beispiel: Slite und Notion.

Best Practices zum Schreiben Ihrer ersten technischen Dokumentation

Sind Sie bereit, Ihre erste technische Dokumentation zu schreiben? Hier sind ein paar Best Practices, die Sie sich merken sollten:

1. Styleguides

Verwenden Sie einen Styleguide, um die Schreib- und Formatierungsstandards Ihrer technischen Dokumente zu verbessern. Wenn Sie noch nie einen Styleguide erstellt haben, sollten Sie diese Komponenten berücksichtigen:

• Ton und Stimme: Definieren Sie den Ton und die Stimme, mit denen Ihre Zielgruppe in Resonanz tritt – formell, informell oder neutral.
• Grammatik und Zeichensetzung: Geben Sie Regeln an, die strikt angewendet werden sollten, und legen Sie die Verwendung von Satzzeichen wie Bindestrichen, Gedankenstrichen, Semikolons, dem Oxford-Komma und Punkten (einzuschließen oder nicht) in Aufzählungs- und nummerierten Listen sowie die Großschreibung fest.
• Formatierungsrichtlinien: Geben Sie die Details zu Schriftarten, die Verwendung von Aufzählungszeichen oder nummerierten Listen (oder beides) und die Verwendung von Emojis und Formatierungsstilen – fett, kursiv und unterstrichen – an.
• Terminologie und Abkürzungen: Geben Sie Richtlinien für die Verwendung der Terminologien an. Sollte das Akronym am Ende der Terminologie nur erwähnt werden, wenn es zum ersten Mal eingeführt wird, oder sollte es jedes Mal erwähnt werden, wenn es im Dokument erwähnt wird?
• Visuelle Elemente: Heben Sie die Regeln für die Verwendung von Visualisierungen im Dokument hervor. Kann die Dokumentation Flussdiagramme enthalten? Oder muss es sich speziell um Produkt-Screenshots und Tutorials handeln? Gibt es eine bestimmte Art und Weise, wie Sie Alt-Texte und Bildunterschriften zu den Bildern hinzufügen müssen?

Zum Beispiel Microsofts Styleguide vollgepackt mit nützlichen Beispielen, einschließlich dessen, was funktioniert und was nicht.

Sie sehen die Tabellen mit Überschriften wie „Verwenden Sie dies“ und „Nicht dies“ beschriftet, um klare Anweisungen zu geben, die es den Lesern erleichtern, die Informationen sofort zu erfassen. Außerdem werden die Szenarien, in denen der technische Redakteur Punkte auslassen muss, einschließlich des Oxford-Kommas, und keine Leerzeichen um Gedankenstriche herum einfügen darf, klar erwähnt.

1. Dokumentationsvorlagen

Verwenden Sie vorgefertigte Dokumentationsvorlagen, anstatt den Inhalt von Grund auf neu zu schreiben – ohne eine richtungsweisende Struktur.

Sie arbeiten nicht auf einer leeren Leinwand. Mit diesen Vorlagen kennen Sie die genauen Abschnitte, die Ihre Dokumentation enthalten wird – das spart Ihnen Zeit und gibt Ihnen Klarheit über die Recherche, die Sie durchführen müssen, und die Erkenntnisse, die Sie von KMUs gewinnen müssen.

Hier ist ein Beispiel für eine vorgefertigte Dokumentationsvorlage:

In der Vorlage erhalten Sie die verschiedenen Abschnitte, die Ihr Dokument enthalten sollte, und Details, die Sie basierend auf Ihrer Recherche hinzufügen können.

1. Inhaltsstruktur

Organisieren Sie Ihre Dokumentation mit klaren Überschriften, Listen und Visualisierungen wie Screenshots, Flussdiagrammen und Video-Tutorials, um den Lesern zu helfen, die Informationen schnell und vereinfacht zu verarbeiten.

Werfen Sie einen Blick auf die API-Dokumentation von Reply.io.

Jeder Abschnitt ist mit verschiedenen Überschriften, nummerierten Listen und Aufzählungszeichen versehen. Um einige Wörter hervorzuheben, haben sie sie fett formatiert und Emojis nur minimal verwendet. Außerdem sieht die Dokumentation sauber aus, da nach jedem Abschnitt ein Leerraum hinzugefügt wurde.

1. Schreibkonvention

Verwenden Sie anstelle von überkomplizierter, ausgefallener Sprache eine einfache, klare Sprache, um es den Lesern zu erleichtern, die komplexen, technischen Informationen zu verstehen.

Konzentrieren Sie sich auf die Verwendung des Aktivs und nur 10 % des Passivs. Stellen Sie außerdem sicher, dass Ihre Sätze prägnant und frei von Füllwörtern sind, um Klarheit in Ihre Dokumentation zu bringen und das Verständnis der Informationen zu vereinfachen.

💡Profi-Tipp: Überprüfen Sie Ihren Lesbarkeitswert auf Hemmingway – er sollte Note 9 oder weniger betragen.

1. Qualitätssicherung

Bevor Sie die Inhalte veröffentlichen, lassen Sie die KMUs die Inhalte auf Richtigkeit und Benutzerfreundlichkeit überprüfen. Führen Sie nach der Veröffentlichung der Inhalte regelmäßige Überprüfungen durch, um die Inhalte auf dem neuesten Stand zu halten.

Zum Beispiel verwenden die interne Dokumentation und die SOPs, die Ihr Team verwendet, die Slites Funktion zur Dokumentenverifizierung, um die KMUs aufzufordern, das Dokument zu überprüfen. Sobald das Dokument verifiziert wurde, wissen alle Teammitglieder, dass die Dokumentation korrekt und einsatzbereit ist.

Schreiben Sie Ihre erste Dokumentation mit Slite

Seien wir ehrlich: die Recherche durchführen, mit KMUs zusammenarbeiten, Feedback einholen und die veröffentlichte Dokumentation pflegen. Das ist eine Menge harter Arbeit.

Es erhöht die Reibung im Content-Erstellungsprozess. Hier werden Dokumentationstools wie Slite zum Ritter in glänzender Rüstung.

Mit Slite können Sie:

Schritt 1: Erfassen Sie Ihre Recherche – Links zu anderer Dokumentation als Referenz, Video-Tutorials oder Screenshots, die Sie in Ihre Inhalte aufnehmen würden, oder die KMU-Videoaufzeichnung, und organisieren Sie sie in Ihrem Slack-Kanal.

Schritt 2: Laden Sie die KMUs in den Workspace ein. Sie können Kommentare zum Recherche-Dokument hinzufügen und ihr Feedback geben, und sogar zusätzliche Ressourcen für die technischen Redakteure.

Schritt 3: Schreiben Sie Ihre erste Dokumentation in Slite oder integrieren Sie das Tool in Google Docs, wenn Sie den Entwurf dort geschrieben haben. KMUs können das Dokument überprüfen und Kommentare hinzufügen und die Redakteure markieren, um Feedback zu geben.

Schritt 4: Fordern Sie die KMUs und Stakeholder auf, das Dokument zu überprüfen, um sicherzustellen, dass die Dokumentation korrekt und auf dem neuesten Stand ist. Sie können dies vor der Veröffentlichung des Dokuments oder sogar nach der Veröffentlichung der Dokumentation tun.

Möchten Sie sehen, wie Slite die Zusammenarbeit Ihres Teams während des technischen Content-Erstellungsprozesses verbessern kann? Testen Sie Slite kostenlos.