Was ist die technische Dokumentation?
Eine komplette technische Dokumentation ist eine Reihe von Dokumenten, die die technischen Merkmale und Funktionen eines Produkts sowie seinen Entwicklungs-, Anwendungs- und Wartungsprozess im Detail beschreiben. Die technische Dokumentation begleitet die Erstellung und Nutzung eines technischen Produkts während seines Lebenszyklus. Die Qualität des zu entwickelnden Produkts, die Anzahl und Kritikalität möglicher Fehler sowie die Kosten für deren Behebung hängen maßgeblich von der Qualität der Dokumentation ab.
Die Dokumentation beginnt mit der Formulierung, Vereinbarung und Genehmigung der Anforderungen an das zukünftige materielle (physische) oder immaterielle (Software) Produkt. Je nach Produktart - ein von einem Kunden bestelltes Einzelprodukt oder eine Massenproduktion für den Verkauf auf dem Markt - variieren die Anforderungen an die Gestaltung und den Inhalt der technischen Dokumentation sowie an den Abstimmungs- und Genehmigungsprozess.
Es gibt jedoch einige grundlegende technische Dokumente, die in jedem Projekt vorhanden sein sollten. Manchmal unterschätzen selbst professionelle Entwickler die Rolle und Bedeutung der technischen Dokumentation für Software und behandeln diese als etwas Nebensächliches und Unwichtiges. Dieses Missverständnis kann sich nicht nur negativ auf die Produktqualität, sondern auch auf den Erfolg des ganzen Projekts auswirken.
Anforderungsspezifikation
Vor allem bei der Erstellung komplexer Produkte, zu denen primär Software zählt, sind es die technischen Anforderungen, die bestimmen, wie das Produkt funktionieren und mit seiner Umgebung interagieren wird, beispielsweise mit anderen Softwarekomponenten und mit dem Anwender.
Je nach Art des Softwareprodukts (Desktop-Programm, mobile App oder Webanwendung) kann die Anforderungsspezifikation Lastenhefte mit den Anforderungen für die Softwareentwicklung und -design, die Service- und Systemintegrationsarbeiten sowie die Automatisierung und Optimierung von technischen Prozessen enthalten. Die in der Anforderungsdokumentation offengelegten Kernpunkte sind die allgemeinen Informationen über das Produkt (Zweck, Anwendung, Geschäfts- und Marketingziele), die Produktmerkmale, die funktionalen Anforderungen, Sicherheits- und Qualitätsanforderungen sowie die Einschränkungen und Besonderheiten der Produktentwicklung und des Betriebes.
Grundsätze der technischen Dokumentation
Inhalt, Formulierungen und Ausdrucksweise der technischen Dokumentation werden weitgehend davon bestimmt, für wen und wofür sie erstellt wird. Die Vereinbarung der einzelnen Punkte und Anforderungen muss mit der Erstellung des Lastenheftes einhergehen. Zu den grundlegenden Prinzipien, auf denen die Spezifikation basiert, gehören die beidseitige Kommunikation mit dem Investor oder dem Kunden, Nachvollziehbarkeit, Klarheit und Verständlichkeit der Anforderungen und Lösungen sowie die Vollständigkeit und Strukturierung der Dokumentation. Selbst eine nicht technisch versierte Person, die die Dokumentation liest, sollte das Konzept und die Schlüsselelemente der künftigen Lösung verstehen. Dadurch werden Situationen vermieden, in denen Anforderungen mehrdeutig sind und von den Entwicklern missverstanden werden können.
Arten der Dokumentation
Technische Dokumentation ist für alle Arten von Produkten notwendig und relevant, einschließlich Medizinprodukten, Software, technischen Produkten und Technologien. Die gesamte technische Dokumentation wird in zwei Haupttypen unterteilt: Verfahrens- und Konstruktionsdokumentation. Die technologische Dokumentation beschreibt den gesamten Zyklus, bestehend aus den Etappen, Phasen und Schritten der Produktentwicklung, vom ersten Entwurf und der technischen Spezifikation bis hin zur Umsetzung. Die Konstruktionsunterlagen enthalten eine Beschreibung der spezifischen Verwendung, Wartung, Reparatur und Entsorgung eines technischen Produkts. Dazu gehören Diagramme, Schaltpläne, Zeichnungen sowie Betriebs-, Wartungs- und Reparaturhandbücher.
Das Dokumentationspaket umfasst nicht nur technisches Material, sondern auch viele andere Arten von Dokumenten. Dazu gehören Handbücher, Anleitungen und Informationen für Benutzer, eine Beschreibung der Interaktion mit der externen Umgebung und anderen Produkten und Komponenten sowie Spezifikationen, Testverfahren, Wartung und Reparaturmöglichkeiten.
Die technische Dokumentation kann zur besseren Einordnung in vier Kategorien eingeteilt werden: Entwurfsdokumentation (Architektur und Design), technische Dokumentation (Beschreibung der Implementierung), Benutzerdokumentation und Marketingunterlagen (Marketingbroschüren, Präsentationen und Videos). Ein Benutzerhandbuch enthält die Beschreibung der Funktionen, Merkmale und Nutzungsbedingungen des Produkts. Dieses Dokument enthält häufig auch Anleitungen zur Fehlerbeseitigung und Antworten auf häufig gestellte Fragen (FAQ).
Erstellung der technischen Dokumentation
Dies sollte von qualifizierten Fachleuten durchgeführt werden, die mit den aktuellen Normen und Standards sowie den behördlichen Anforderungsdokumenten vertraut sind. Die Verfasser technischer Dokumente müssen mit den Besonderheiten des Entwicklungs-, Implementierungs- oder Herstellungsprozesses, der Implementierung, des Betriebs und der Wartung des Produkts vertraut sein. Als Tech-Writer müssen sie in der Lage sein, alle relevanten Informationen in einer klaren und präzisen Sprache auszudrücken.
Die Dokumentation muss bestimmten Qualitätsanforderungen genügen. Sie sollte strukturiert und vollständig (einschließlich Screenshots, Abbildungen, Videos), einheitlich (in einem einzigen, einheitlichen Stil), konsistent mit anderen Unternehmensdokumenten, informativ und verständlich, relevant und nützlich für das Zielpublikum sein.
Richtig konzipierte, ausgearbeitete und geschriebene technische Unterlagen spiegeln alle Produktionsstufen wider, beschreiben die Besonderheiten der Produktion, Nutzung und Wartung und ermöglichen es, den gesamten Prozess zu kontrollieren und, falls erforderlich, sowohl den Prozess als auch das Produkt selbst zu verbessern, Mängel zu beseitigen und die Qualität zu steigern. Dies verlängert den Lebenszyklus und erhöht die Zuverlässigkeit und Sicherheit, verringert das Missbrauchsrisiko und liefert den Entwicklern umfassende dokumentierte Informationen über das Produkt sowie potenziellen Partnern und Nutzern die notwendigen technischen Informationen.
Die Design- und Produktanforderungen sollten dokumentiert und vereinbart werden, bevor die Produktentwicklung beginnt. Die übrigen Dokumente werden in der Regel im Laufe des Projekts erstellt, parallel zu anderen Projektphasen. Moderne IT-Projekte werden in der Regel nach der agilen Methodik durchgeführt, und die Dokumentationsarbeit erfolgt parallel zum Entwicklungsprozess. Bevor eine bestimmte Phase beginnt, sollten die für ihre Durchführung erforderlichen Unterlagen fertig sein.
Die technische Dokumentation wird von einem technischen Redakteur (Technical Writer) erstellt. Er verfasst fast alle Arten von Materialien, darunter Benutzer- und technische Handbücher, Funktionsbeschreibungen und Marketingtexte.
Dokumentationserstellung
Die Verfassung und Verwendung technischer Dokumentationen ist ein integraler Prozess in jedem Industrieunternehmen und jeder Softwareentwicklungsfirma. Eine ordnungsgemäß erstellte technische Dokumentation ist eine Garantie für die erfolgreiche Herstellung und Vermarktung von Produkten. Daher ist es besser, die Verfassung der technischen Dokumentation Fachleuten anzuvertrauen, die selbst Erfahrung in der Entwicklung von Produkten dieser Art haben und ein ganzes Paket technischer Unterlagen unter Berücksichtigung der Besonderheiten des Produkts, der bestehenden Anforderungen, Normen und Standards erstellen können.
Es gibt Projekte, bei denen es wichtig ist, dass vor Beginn der Arbeiten eine vollständige Dokumentation vorliegt. Dies gilt für sicherheits- und missionskritische Lösungen mit erhöhten Qualitätsanforderungen. Dies wird mehr Zeit in Anspruch nehmen, lässt aber finanzielle und rufschädigende Risiken vermeiden. Die Kosten für die Erstellung der technischen Dokumentation werden durch den Projekttyp bestimmt und hängen von Faktoren wie der Anzahl der Dokumente, dem Grad der technologischen Komplexität des Produkts und der Kritikalität seiner Verwendung, dem Massen- oder Einzelauftragscharakter, der Notwendigkeit der Registrierung und Genehmigung durch andere Organisationen oder Partner ab.
Fazit
Qualitativ hochwertige technische Unterlagen sollten klar strukturiert sein, in einem einheitlichen Format erstellt werden und sowohl für Fachleute als auch für Benutzer verständlich und informativ sein. Das wichtigste Merkmal der technischen Dokumentation ist ihre Relevanz für die Bedürfnisse und Anforderungen der Zielgruppe. Die Erstellung der technischen Dokumentation liegt in der Verantwortung eines technischen Redakteurs. Er muss nicht nur die entsprechenden Texte schreiben und redaktionell bearbeiten, sondern auch Grafiken, Videos und Präsentationen erstellen, Produktinformationen sammeln, die Dokumentation in Fremdsprachen übersetzen und das Produkt analysieren und bewerten können.
Art, Umfang und Inhalt der technischen und technologischen Dokumentation hängen von der Projektart, dem Zweck und der Spezifik des jeweiligen Produkts ab sowie von der Erfahrung und Kompetenz der Autoren. Die Erstellung der Dokumentation ist eine der wichtigsten Phasen im Produktentwicklungsprozess. Dokumentation wird für alle Arten von technischen Produkten und Projekten in ihrem Lebenszyklus benötigt. Eine unzureichende Beachtung der Qualität der Dokumentation, ihres Inhalts und ihrer Gestaltung kann sich kritisch auf die Produktentwicklung und -Qualität sowie auf die erfolgreiche Produktnutzung und den Projekterfolg auswirken.