Produktteams und Softwareteams haben ein gemeinsames Problem: die Dokumentation.
Die Produktdokumentation bezieht sich auf Handbücher und Leitfäden für die Benutzer, die den Arbeitsablauf und die Benutzeroberfläche eines Produkts erklären. Wie kann der durchschnittliche Benutzer mit diesem Produkt produktiv arbeiten? In diesem Sinne könnte die Produktdokumentation auch für Softwareprodukte verwendet werden.
Die Softwaredokumentation bezieht sich auf die zugrunde liegenden Technologien, Voraussetzungen und konfigurierbaren Eigenschaften eines Softwareprodukts. Wie konfigurieren, überwachen, hosten und verteilen IT-Administratoren das Softwareprodukt für die Benutzer? Diese Art von Dokumentation ist wichtig, vor allem, wenn mehrere Versionen oder Zweige hinzukommen.
In gewisser Weise ist die Produktdokumentation so, als würde man jemandem beibringen, wie man ein Auto fährt. Das Lenkrad dreht das Auto, das Gaspedal bewegt das Auto, das Bremspedal stoppt das Auto. Bei der Software-Dokumentation lernt man, wie das Auto funktioniert. Das Rad ist mit der Vorderachse verbunden, die die Vorderreifen dreht, um die Fahrtrichtung zu ändern; das Gaspedal erhöht den Luftstrom zum Motor, der mehr Kraftstoff ansaugt und Drehmoment und Leistung erzeugt.
Beide Dokumentationsarten sind wichtig. Die eine schult die Benutzer, die andere die Administratoren und Entwickler. Es ist toll, den Leuten zu zeigen, wie man ein Auto fährt, aber wenn niemand weiß, wie das Auto funktioniert, was passiert dann, wenn das Auto kaputt geht?
Kleine Unterschiede zwischen Produkt- und Software-Dokumentation
Zwischen Produkt- und Software-Dokumentation gibt es kleine Unterschiede, die Sie beachten sollten:
Software- und Produktdokumentation: Zielpublikum und Persona
Die Produktdokumentation wendet sich an eine einzige Zielgruppe: den Benutzer. Sie setzt voraus, dass der Benutzer kein technisches Wissen hat, und kommuniziert in einfachem Englisch mit minimalem Fachjargon. Ähnlich wie bei einer technischen Ausbildung im Gegensatz zu einem Universitätsabschluss wird den Menschen beigebracht, wie sie etwas tun können, wobei der Schwerpunkt weniger auf theoretischem oder konzeptionellem Wissen liegt.
Software-Dokumentation richtet sich an IT-Administratoren, Ingenieure und Entwickler. Sie umfasst das Design und die Architektur der Software, Anweisungen für die Einrichtung der Befehlszeile, API- und Integrationsunterstützung, Datenverwaltung und Berichterstellung, Netzwerktopologie - im Grunde die Rädchen, die die Maschine zum Laufen bringen. Diese Dokumente bilden eine "Single Source of Truth" (SSOT), auf die sich das IT-Personal bei der Überwachung und Fehlersuche in der Softwareanwendung beziehen kann.
Software- und Produktdokumentation: Aktualisierungshäufigkeit
Die Softwaredokumentation muss ständig aktualisiert werden, wenn neue Commits in den Hauptversionskanal integriert werden. In der Softwaredokumentation müssen neue Funktionen und Befehle hervorgehoben und alte Funktionen veraltet sein. Neue oder geänderte Abhängigkeiten sollten dokumentiert werden, und die Unterstützung von Funktionen auf allen Zielplattformen sollte geklärt werden - z. B. wenn eine Funktion unter Windows funktioniert, aber nicht unter Linux.
Die Produktdokumentation muss nur dann aktualisiert werden, wenn die zugrundeliegenden Softwareänderungen eine Änderung des Arbeitsablaufs oder der Benutzerfreundlichkeit zur Folge haben. Ein Entwickler ändert den Code eines Zahlungs-Gateways, aber der Zahlungsvorgang für die Benutzer bleibt derselbe, so dass keine Aktualisierungen erforderlich sind.
Dies zeigt eine natürliche Hierarchie für die Dokumentation von Softwareprodukten. Die technische Softwaredokumentation bildet die Grundlage, und die nachfolgende Produktdokumentation baut auf dieser Grundlage auf. Daher sollte der Schwerpunkt auf der Erstellung einer guten Softwaredokumentation liegen, da diese eine noch bessere Produktdokumentation hervorbringt.
Beispielhafte Formatierungsrahmen für Produkt- und Softwaredokumentation
Ein Stück Produktdokumentation könnte diesem Rahmen folgen:
- Produktname
Übersicht über den Zweck des Produkts
-
Einrichtungsanleitung
-
Erläuterung und Bilder zu Merkmal 1*
-
Feature 2 Erläuterung und Bilder * *Feature 2 Erläuterung und Bilder
-
Links zum Kundensupport*
In ähnlicher Weise könnte eine Software-Dokumentation diesem Rahmen folgen:
- Software-Name
Übersicht über den Zweck der Software
Software-Abhängigkeiten
-
Installationsanleitung
-
Erläuterung der Funktion 1 und Bilder*
-
Funktion 2 Erklärung und Bilder
-
Links zum technischen Support*
Es liegt auf der Hand, dass diese beiden Dokumentationsarten eng miteinander verbunden sind und einer ähnlichen Struktur folgen. Das bedeutet, dass Produkt- und Softwareteams viel voneinander lernen können und dass die Zusammenarbeit bei der Dokumentation ein großes Potenzial bietet.
Produkt- und Software-Dokumentationsteams können sich gegenseitig ergänzen
Zwischen Produkt- und Softwaredokumentation gibt es große Ähnlichkeiten. Das wirft die Frage auf: Können Produkt- und Softwareteams zusammenarbeiten?
Ja, das können sie, und das sollten sie auch!
Softwareteams verstehen den Fachjargon und die zugrunde liegenden Technologien. Produktteams verstehen, was die Benutzer sehen, wollen und brauchen; die Benutzererfahrung. Autoren von Software-Dokumentationen können detaillierte technische Informationen liefern, und Autoren von Produktdokumentationen können die technischen Details für ein Laienpublikum verdünnen.
Stellen Sie sich vor, Sie versuchen, etwas in Laiensprache zu erklären, ohne über das nötige Verständnis auf hohem Niveau zu verfügen, um etwas zu formulieren, das ein Laie verstehen würde. Genau das passiert, wenn die Produktdokumentation vor der Softwaredokumentation erstellt wird.
Was ist Quantenmechanik? Schrödingers Katze ist wahrscheinlich der erste Gedanke in Ihrem Kopf! Aber was hat die Quantenmechanik mit Katzen zu tun? Für den Benutzer ist das nicht wichtig. Für einen Physiker bedeutet sie alles.
Beginnen Sie mit Software-Dokumentation, enden Sie mit besserer Produktdokumentation in Docsie
Zusammenfassend lässt sich sagen, dass die Verwendung einer Software-Dokumentation als Vorlage für eine spätere Produktdokumentation viele Vorteile mit sich bringt. Die Softwaredokumentation sollte für IT-Mitarbeiter und Produktdokumentationsautoren als einzige Quelle der Wahrheit dienen. Nach dem Verfassen der Dokumentation haben die Verfasser der Produktdokumentation die Klarheit und das Verständnis, um das Wissen zu vereinfachen und benutzerfreundlich an die Kunden weiterzugeben, mit technischer Anleitung zum Korrekturlesen und zur Qualitätssicherung.
Wenn Sie mit einer guten Software-Dokumentation beginnen, können Ihre Autoren eine noch bessere Produktdokumentation erstellen!
Beginnen Sie mit der Erstellung von Dokumentationen, die Ihren Kunden helfen, mehr zu erreichen. Melden Sie sich für unseren Startup-Plan (forever free!) an und liefern Sie mit Docsie begeisternde Dokumentation!