Wie man technische Dokumentation mit Beispielen erstellt

Alle Softwareprodukte mit einfachen oder komplexen Bedürfnissen sollten von einer technischen Dokumentation begleitet werden, um Stakeholdern und Entwicklern zu helfen, die Softwareentwicklung zu verstehen. Es endet dort nicht – es erfordert auch Produktdokumentation und Benutzerhandbücher zugunsten des Kundeneinstiegs und der Nutzung des Produkts.

Ohne technische Dokumentation stehen Entwickler und Kunden im Dunkeln über den Zweck ihrer Software. Es wird schwierig, Probleme zu lösen und sicherzustellen, dass die Software richtig funktioniert.

Technische Dokumentation ist ein wesentlicher Aspekt der funktionierenden Software und sollte nicht während des Release-Zyklus übersprungen werden. Ob Versionshinweise, Wissensdatenbanken oder Benutzerhandbücher – denken Sie daran, dass 51% aller Kunden auf einer Website einen FAQ-Abschnitt sehen möchten, wenn sie einen Online-Kauf durchführen.

„Docs or it did not happen“ ist ein Mantra für jeden, der ein Softwareprodukt aufbaut. und bedeutet, dass Dokumentation mehr ist als ein Nebenprodukt oder ein nachträglicher Gedanke bei Ihrem Projekt. Es schließt die Lücke zwischen Entwicklern und Software-Anwendern sowie die Lücken zwischen denen, die am Aufbau der Software beteiligt sind.

Was ist technische Dokumentation?

Technische Dokumentation beschreibt und erklärt alles, was mit Ihrem Softwareprodukt zu tun hat – sie reicht von der internen Dokumentation für Teams bis hin zur externen Dokumentation für Endanwender. Es umfasst alle schriftlichen Dokumente zur Produktentwicklung und viele verschiedene Typen werden während des gesamten Software-Entwicklungslebenszyklus (SDLC) erstellt.

Es beschreibt die Funktionen und die Funktionalität des Produkts, so dass jeder es nutzen kann. Das Hauptziel ist es, dem Zielpublikum einen bestimmten Aspekt des Produkts zu erklären. Obwohl es in einer Reihe von verschiedenen Formen erscheint, werden die meisten technischen Dokumentationen online veröffentlicht und normalerweise von technischen Redakteuren, Entwicklern und Projektmanagern geschrieben.

Technische Dokumentation sollte klar, präzise und genau sein und tatsächlich ein Problem für Ihre Benutzer lösen.

Bedeutung der technischen Dokumentation

Technische Dokumentation ist für Ihr Softwareunternehmen von entscheidender Bedeutung. Dies sind einige Gründe dafür.

Ermöglicht schnelle Entscheidungsfindung durch das Produktteam

Wenn Ihr Produktteam Zugriff auf die richtigen technischen Unterlagen hat, können diese wesentlich schnellere Entscheidungen treffen. Sie müssen nicht durch E-Mails oder Threads in Kollaborationswerkzeugen zurückscrollen – sie können stattdessen sofort in die zusammen mit der Software erstellten Dokumente nachschlagen- Diese erklären, wie alles funktioniert und zeichnen die Argumentation hinter den Entscheidungen auf.

Kontextbezogene Hilfe für Benutzer

Wenn Kunden ihre Software verwenden, können sie neben dem Produkt auch auf Ihre technische Dokumentation zugreifen, um Hilfe bei der Verwendung des Tools zu erhalten. Dokumentation kann in der App angezeigt werden, so dass Kunden bei Problemen keine Kontexte wechseln müssen. Dies verbessert die allgemeine Benutzerfreundlichkeit und Erfahrung Ihres Softwareprodukts.

Marketing-Werkzeug

Eine robuste technische Dokumentation erleichtert die Werbung für Ihr Produkt bei potentiellen Kunden. Viele Kunden werden gründlicher recherchieren, wie Ihr Produkt funktioniert und da kann die technische Dokumentation Ihre Software-Features detaillierter erklären als die typischen Marketingmaterialien.

Reduziert Technik-Supportanrufe

Wenn Sie eine umfassende technische Dokumentation haben, können sich Kunden bei technischen Problemen die Dokumentation ansehen. Dadurch wird die Anzahl der eingehenden Anrufe reduziert, die Sie in Ihrer technischen Support-Leitung bekommen und Sie können mehr Kunden mit einem kleineren Budget unterstützen. Die meisten Kunden ziehen es vor, Probleme selbst zu beheben, anstatt auf eine Person zu warten, um ihnen zu helfen.

Entwicklervorschläge aufzeichnen

Ihre Software-Dokumentation kann Ideen aufzeichnen, die Ihre Entwickler in Bezug auf Ihr Softwareprodukt haben. Selbst wenn man sie nicht sofort umsetzt. können Sie zu einem späteren Zeitöunkt auf Funktionen zurückblicken, die Sie vielleicht in Erwägung ziehen oder weitere Änderungen vornehmen möchten. Später erinnern sich Entwickler nicht unbedingt an ihre Ideen, so dass Ihre Dokumentation ein guter Ort ist, um einen Datensatz zu führen.

Gibt einen Aktionsplan für zukünftige Projekte an

Ihre technische Dokumentation ist ein Aktionsplan für Projekte, die Sie in Zukunft entwickeln möchten, mit Blick auf die Pläne für die Entwicklung Ihres Produkts und neue Funktionen, die sich in der Entwicklungsphase befinden. Es stellt sicher, dass jeder in Ihrem Team auf der gleichen Seite ist und auf ein einziges Ziel hinarbeitet.

Verbessert die Kommunikation mit Stakeholdern und Entwicklern

Dokumentation ist eine wichtige Form der Kommunikation – Ihre Stakeholder und Entwickler müssen nicht direkt miteinander reden, um auf Informationen über die Software zuzugreifen. Ihre Dokumentation speichert Wissen für die Nachwelt und ermöglicht Ihrem Team, auf die bisher erledigte Arbeit zurückzublicken, um deren zukünftige Entscheidungen zu informieren.

Lesen Sie mehr: Was ist technische Dokumentations-Software?

Arten der technischen Dokumentation mit Beispielen

Es gibt viele verschiedene Arten von technischen Dokumentationen – wir werden sie jetzt durchgehen.

Technische Dokumentation in SDLC

Dies ist Ihre Dokumentation hinter den Kulissen für Ihre Entwickler und andere Teammitglieder.

Die Dokumentation des Systemadministrators – verbessert und validiert die Sicherheit, indem die Konfigurationsdetails und Prozeduren dokumentiert werden, die eine Sicherheitsrichtlinie untermauern. Sie umfassen Installationen und Updates, die einem Systemadministrator bei der Produktpflege helfen.

Bildquelle

Dokumentation zur Produktanforderung – bietet einen einzigen Bezugspunkt für die technischen Anforderungen eines Produkts und erklärt, wie das Produkt funktionieren muss, um den Bedürfnissen der Kunden gerecht zu werden.

Bildquelle

Dokumentation zum Benutzererfahrungsdesign – ein funktionierendes Dokument eines Produkts von der Konzeption bis zur aktuellen Version, und sie enthält Inhaltsmodelle, Empathiekarten, Erfahrungskarten, mentale Modelle und Personen.

Bildquelle

Quellcode-Dokumentation – Software-Dokumentation, die sicherstellt, dass Ihr Code lesbar ist, schnell verstanden werden kann und leicht von Entwicklern gepflegt werden kann. Es enthält Codekommentare, diejenigen Teile des Codes erklären können, die nicht offensichtlich sind.

Bildquelle

API-Dokumentation – ermöglicht Entwicklern, mit Ihrer API zu arbeiten und zeigt an, ob Ihre Software ihr Problem löst oder nicht.

Bildquelle

Wartungshinweis-Dokumentation – teilt dem Benutzer mit, wie er das System effektiv pflegt und kann eine Definition der Software-Support-Umgebung, der Rollen und Verantwortung des Wartungspersonals enthalten.

Bildquelle

Produktdokumentation

Produktwissen – eine Bibliothek mit Informationen über Ihr Softwareprodukt, die Antworten für Kunden enthält, die Probleme alleine lösen möchten.

Bildquelle

Lesen Sie mehr: Wie Sie SaaS Produktdokumentation für Ihre Kunden erstellen

Benutzerhandbuch – enthält ausführliche Informationen zur Installation und Bedienung des Produkts, listet die Hard- und Softwareanforderungen, und bietet eine vollständige Erläuterung der Produktfunktionen und deren vollständige Nutzung.

Bildquelle

Lesen Sie mehr: Top Online-Benutzerhandbücher für 2024

Projektdokumentation – protokolliert die wichtigsten Projektdetails und erzeugt die für die erfolgreiche Umsetzung eines Projekts erforderlichen Dokumente. Es kann Projektvorschläge, Geschäftsdokumente, Geschäftsfälle, Projektpläne und Projektstatusberichte enthalten.

Bildquelle

Auch lesen: Top Technische Dokumentation KPIs zum Tracken

8 Schritte zur Erstellung von unglaublichen technischen Dokumentationen

Hier sind die Schritte, die Sie durchlaufen müssen, um technische Dokumentation zu erstellen, die sowohl erfolgreich als auch hilfreich für Ihre Benutzer ist.

Entscheiden Sie sich über Art des Publikums und Art der Dokumentation

Zuallererst müssen Sie sich der Zielgruppe für Ihre Dokumentation bewusst sein. Sind es Ihre Kunden, andere Entwickler, Produktteams oder irgendwelche andere Stakeholder? Indem Sie wissen, wer Ihr Publikum ist, können Sie den Ton und Stil Ihrer Dokumentation anpassen, um sie relevanter und interessanter zu machen.
 Wenn Sie nicht wissen, wer Ihr Publikum ist, wird Ihre Dokumentation nicht fokussiert und nicht hilfreich sein. Ihre Zielgruppe am Anfang Ihres Dokumentationsprozesses zu definieren, hilft Ihnen bei der Erstellung von Dokumenten und stellt sicher, dass Sie ein klar definiertes Ziel haben.

Forschung zu Themen

Sobald Sie Ihr Publikum definiert haben, müssen Sie die Themen erforschen, die Sie in Ihrer Dokumentation behandeln werden. Sie können nicht hoffen, effektive technische Inhalte zu schreiben, wenn Sie keine klare Vorstellung von den Themen haben, über die Sie schreiben werden. In dieser Phase ist es eine gute Idee, mit Ihrem Team zusammenzuarbeiten, um verschiedene Themen zu entwickeln und verschiedenen Teammitgliedern verschiedene Forschungsaufgaben zuzuordnen.

Es ist wichtig, sich selbst Fragen zu stellen wie:

• Welche Bereiche wollen wir in unsere technische Dokumentation einbeziehen?
• Was ist das Ziel, das wir mit unserer technischen Dokumentation erreichen wollen?
• Gibt es bereits existierende Dokumentationen, mit denen wir bereits arbeiten können?

Stellen Sie sicher, dass es ein Team gibt, die Themen zu erforschen – Sie müssen es nicht alleine tun.

Wissen erfassen

Wenn Sie Ihre Dokumentation schreiben, werden Sie wahrscheinlich nicht der einzige Autor sein. Sie müssen mit anderen Stakeholdern Ihres Teams zusammenarbeiten, um technische Dokumentation erstellen zu können. In diesem Stadium müssen Sie mit Subject Matter Experten arbeiten, um Wissen zu erfassen, die Sie verwenden werden, um Ihre Artikel zu schreiben.

Nehmen Sie sich Zeit, um herauszufinden, wer die geeignetste Person ist, um verschiedene Themen Ihrer technischen Dokumentation zu verfassen, und wenden Sie sich an diese, um ihnen die Aufgabe zuzuweisen. Sie können auch Interviews mit Ihren KMU führen und den Inhalt selbst schreiben.

Führen Sie detaillierte Aufzeichnungen zu Ihren Themen und den Verantwortlichen für die Bereitstellung der Inhalte und verfolgen Sie den Stand Ihrer Inhalte.

Vorlagen entwerfen und Inhalte organisieren

Während der wichtigste Teil Ihrer Dokumentation der tatsächlich geschriebene Inhalt ist, ist es auch eine gute Idee darüber nachzudenken, wie Ihre Dokumentation für den Endbenutzer visuell aussieht. Sie streben eine gut organisierte und visuell ansprechende Dokumentationsseite an und nicht einen Wirrwarr aus schlecht gestalteten Notizen, die niemandem hilft.

Betrachten Sie bei der Planung von Dokumentationen die Struktur und Navigation Ihrer Inhalte. Ihre Benutzer wenden sich in der Regel an technische Dokumentation, um spezifische Informationen oder eine Lösung für ein Problem zu finden. Ihre Recherche sollte es ihnen ermöglichen, diese Aufgabe schnell zu erledigen.

Denken Sie daran, Ihre Informationen in Kategorien und Unterkategorien zu platzieren, durch die Benutzer effizient durchsuchen können. Idealerweise sollten Sie eine Suchleiste haben, mit der Benutzer sofort zu den Informationen springen können, die sie suchen.

Beginnen Sie mit der Erstellung von Inhalten

Sie sollten den Schreibprozess bereits mit der Dokumentenforschung und der Zusammenarbeit mit KMU begonnen haben. Technische Dokumentation zu schreiben ist eine Anstrengung des Teams und Sie werden viele Mitwirkende haben, die an diesem gemeinschaftlichen Prozess teilnehmen.

Content-Aufgaben an das geeignetste Mitglied, basierend auf seinen Fähigkeiten. Die beste Dokumentation wird erzeugt, wenn Autoren mit Umrissen beginnen und ihre Dokumentation an einen bestimmten Benutzer richten.

Ihre Dokumentation sollte mit einer Hochrangigen Umrisslinie für jedes der abzudeckenden Themen beginnen. Sammeln Sie den Rest der Inhalte, die Sie für Ihr Stück benötigen, zusammen mit allen unterstützenden Bildern.

Denken Sie daran, in einer klaren und deutlichen Sprache zu schreiben, die für den Benutzer leicht verständlich ist. Nehmen Sie nicht an, dass die Leser das gleiche Niveau an Vorwissen haben wie Sie – fügen Sie so viel Kontext wie möglich ein, um beim Verständnis zu helfen. Schreiben Sie so viel Inhalt wie nötig, um Ihren Punkt zu vermitteln und keib Wort mehr – Weniger ist definitiv besser, wenn es um Dokumentation geht.

Überprüfen und mit Ihrem Team zusammenarbeiten

Sobald Sie mit Ihren Inhalten begonnen haben, müssen Sie KMU einbinden, um Ihre Inhalte auf Richtigkeit zu überprüfen. Beziehen Sie sie direkt nach dem ersten Entwurf und nach dem endgültigen Entwurf ein, um ihr Feedback zu Ihrer Dokumentation zu bekommen. Nach dem ersten Entwurf möchten Sie ein Feedback über die allgemeinen Umrisse und den Umfang des Dokuments erhalten, anstatt über Tippfehler und Grammatik zu berichten. Erst nach der abschließenden Überprüfung wollen Sie tiefgreifende Kritik an der Art und Weise, wie Sie Ihren Inhalt geschrieben haben.

Suchen Sie Peer-Reviews mit anderen Mitgliedern Ihres Teams, die Ihre technische Dokumentation auf Benutzerfreundlichkeit testen können. Bitten Sie jemanden, Ihre Dokumentation zu überarbeiten und alle Bereiche aufzuzeichnen, in denen sie verloren oder verwirrt wurden. Sobald Sie Ihr Peer-Review-Feedback haben, fügen Sie die Änderungen in Ihre Dokumentation ein.

Sehen Sie auch unseren Artikel: Wie man die Verwendbarkeit von technischen Dokumenten testen kann

Inhalt veröffentlichen

Wenn Sie Ihren Inhalt mehrmals überprüft haben, ist es an der Zeit, Ihre Dokumentation für Ihr Publikum bereitzustellen. Wenn Ihre Dokumentation live ist, überprüfen Sie diese und stellen Sie sicher, dass sie fehlerfrei ist.

Wenn Sie Ihre Inhalte veröffentlichen, können Sie Wissensdatenbank-Software wie Document360 verwenden, was eine gute Möglichkeit ist, Ihre Dokumentation zu verwalten. Es verfügt über eine eingebaute Informationsarchitektur und Kategorie-Organisation sowie eine markante Suchleiste und mobile Reaktionsfähigkeit.

Eine intuitive Wissensdatenbank-Software, um einfach Ihre Inhalte hinzuzufügen und in jede Anwendung zu integrieren. Probieren Sie Document360 aus!

Los geht’s

Nachdem Ihre Website live ist, möchten Sie unter Umständen weitere Tests über die Wirksamkeit der Dokumentation durchführen, indem Sie Feedback von Ihren Benutzern sammeln. Prüfen Sie die Navigation Ihrer Dokumentation, um zu überprüfen, ob Benutzer leicht umgehen können und finden können, was sie suchen – identifizieren Sie Dinge wie kaputte Links und dass Navigationselemente funktionieren.

Dokumentation anhand von Analysen aktualisieren und verwalten

Ihre technische Dokumentation ist nie fertig. Wenn Sie die entsprechende Software verwenden, haben Sie Analysen, die Sie überprüfen können, wie effektiv Ihre Inhalte sind. Sie sollten Ihre Dokumentation immer auf Aktualisierungen überprüfen und nicht verstreichen lassen.

Sie müssen Ihre Dokumentation in Übereinstimmung mit neuen Produkt-Releases und Updates halten. Planen Sie die regelmäßige Pflege Ihres Inhalts auf der Grundlage von Einsichten, die Sie aus Ihrer Analyse sammeln, wie z. B. fehlgeschlagene Suchen oder negative Artikelbewertungen.

Wenn Sie die richtige Software verwenden, können Sie frühere Versionen Ihrer Dokumentation speichern, falls Sie später darauf zurückgreifen müssen.

Do’s und Dont’s bei technischer Dokumentation

Do:

• Halten Sie es einfach und klar – komplizieren Sie Ihre Dokumentation nicht übermäßig oder verwenden Sie keine komplexe Sprache.
• Denken Sie immer an Ihren Benutzer – wann auch immer Sie eine Dokumentation schreiben, stellen Sie sicher, dass Sie wissen, für wen es gemeint ist.
• Machen Sie es visuell – wenn Sie darstellen können, was Sie mit einem Bild zu übermitteln versuchen, dann tun Sie das.
• Führen Sie einen gründlichen Überprüfungsprozess durch – wenn Sie können, stellen Sie sicher, dass mehrere Personen Ihre Arbeit während der Schreibphase überprüfen.

Dont’s :

• Nehmen Sie nicht an, dass Ihr Publikum mit Ihrem Thema vertraut ist – stellen Sie immer so viel Kontext wie möglich.zur Verfügung.
• Verwenden Sie kein Passiv – verwenden Sie stattdessen immer das Aktiv: „Er drückte die Taste“ statt „die Taste wurde von ihm gedrückt“.
• Verwenden Sie keine Akronyme – wenn Sie Abkürzungen verwenden müssen, geben Sie die Bedeutung des Akronyms ganz klar daneben an.
• Versuchen Sie nicht, lustig zu sein – was Ihnen amüsant sein könnte, könnte für Ihre Leser abwertend oder beleidigend sein.

Auch lesen: Wie schreibe ich Inklusive Dokumentation?

Schlussbetrachtungen

Machen Sie nicht den Fehler, zu unterschätzen, wie wichtig technische Dokumentation für den Gesamterfolg Ihres Unternehmens ist. Es ist ein wesentlicher Teil der Kommunikation und bedeutet, dass Mitglieder Ihres Teams nicht tatsächlich verfügbar sein müssen, wenn jemand eine Frage hat; ob dies ein Kunde oder ein Stakeholder aus Ihrem Team ist.

Sie müssen sich der technischen Dokumentation nicht schweren Herzens zuwenden – wenn Sie den Schritten folgen, die wir in dieser Anleitung beschrieben haben, dann sind Sie auf dem besten Weg, um Inhalte zu erstellen, die für Ihre Benutzer hilfreich sind. Sie werden dazu ermächtigt, Ihr Produkt zu verwenden und mehr Spaß mit ihm zu haben, was genau das Ziel der technischen Dokumentation ist.

Interessiert an der Wissensdatenbank Document360? Planen Sie eine Demo mit einem unserer Experten.

Demo buchen