Produkt- und Software-Teams haben ein gemeinsames Problem: Dokumentation¶

Produktdokumentation umfasst benutzerorientierte Handbücher und Anleitungen, die Arbeitsabläufe und Benutzeroberflächen eines Produkts erklären. Sie beantwortet die Frage: Wie kann ein durchschnittlicher Nutzer mit diesem Produkt produktiv arbeiten? Diese Art der Dokumentation wird häufig für Softwareprodukte verwendet.

Softwaredokumentation befasst sich mit den zugrundeliegenden Technologien, Voraussetzungen und konfigurierbaren Eigenschaften eines Softwareprodukts. Sie beantwortet: Wie konfigurieren, überwachen, hosten und implementieren IT-Administrator:innen das Softwareprodukt für Benutzer? Diese Dokumentationsart ist besonders wichtig, wenn mehrere Versionen oder Branches ins Spiel kommen.

Bildlich gesprochen gleicht Produktdokumentation dem Fahrunterricht. Das Lenkrad steuert das Auto, das Gaspedal beschleunigt, die Bremse stoppt das Fahrzeug. Softwaredokumentation erklärt hingegen, wie das Auto funktioniert: Das Lenkrad ist mit der Vorderachse verbunden, die die Vorderräder dreht und so die Fahrtrichtung ändert; das Gaspedal erhöht den Luftstrom zum Motor, der mehr Kraftstoff ansaugt und Drehmoment sowie Leistung erzeugt.

Beide Dokumentationstypen sind wichtig. Einer schult Benutzer, der andere Administrator:innen und Entwickler:innen. Es ist gut, Menschen das Autofahren beizubringen – aber wenn niemand weiß, wie ein Auto funktioniert, was passiert dann bei einer Panne?

Kleine Unterschiede zwischen Produkt- und Softwaredokumentation¶

Bei Produkt- und Softwaredokumentation gibt es einige wichtige Unterschiede:

Zielgruppen und Personas¶

Produktdokumentation richtet sich an eine einzige Zielgruppe: die Benutzer:innen. Sie geht davon aus, dass diese keine technischen Kenntnisse haben, und kommuniziert in einfacher Sprache mit minimalem Fachjargon. Ähnlich einer technischen Ausbildung im Vergleich zu einem Universitätsstudium vermittelt sie praktisches Wissen mit weniger Fokus auf theoretische oder konzeptionelle Kenntnisse.

Softwaredokumentation zielt auf IT-Administrator:innen, Ingenieur:innen und Entwickler:innen ab. Sie behandelt Design und Architektur der Software, Einrichtungsanweisungen für die Kommandozeile, API- und Integrationsunterstützung, Datenmanagement und Berichterstattung, Netzwerktopologie – im Grunde die Zahnräder, die die Maschine antreiben. Diese Dokumente bilden eine zentrale Informationsquelle (Single-Source-of-Truth), auf die IT-Mitarbeiter:innen bei der Überwachung und Fehlerbehebung der Softwareanwendung zurückgreifen können.

Aktualisierungshäufigkeit¶

Softwaredokumentation muss kontinuierlich aktualisiert werden, wenn neue Commits in den Hauptveröffentlichungskanal eingepflegt werden. Sie muss neue Funktionen und Befehle hervorheben und veraltete Funktionen kennzeichnen. Neue oder sich ändernde Abhängigkeiten sollten dokumentiert und die Funktionsunterstützung auf allen Zielplattformen verdeutlicht werden – etwa wenn eine Funktion unter Windows, aber nicht unter Linux funktioniert.

Produktdokumentation muss nur aktualisiert werden, wenn Softwareänderungen zu einer Änderung des Arbeitsablaufs oder der Benutzerfreundlichkeit führen. Wenn ein Entwickler den Code für ein Zahlungs-Gateway ändert, der Zahlungsvorgang für Benutzer jedoch gleich bleibt, sind keine Aktualisierungen erforderlich.

Dies zeigt eine natürliche Hierarchie für die Dokumentation von Softwareprodukten. Technische Softwaredokumentation bildet das Fundament, auf dem die Produktdokumentation aufbaut. Der Fokus sollte daher auf hervorragender Softwaredokumentation liegen, da diese noch bessere Produktdokumentation hervorbringt.

Beispiel-Frameworks für Produkt- und Softwaredokumentation¶

Eine Produktdokumentation könnte diesem Rahmen folgen:

• Produktname
• Überblick über den Produktzweck
• Einrichtungsanleitung
• Erklärung und Bilder zu Funktion 1
• Erklärung und Bilder zu Funktion 2
• Kundenservice-Links

Eine Softwaredokumentation könnte ähnlich aufgebaut sein:

• Softwarename
• Überblick über den Softwarezweck
• Software-Abhängigkeiten
• Installationsanleitung
• Erklärung und Bilder zu Funktion 1
• Erklärung und Bilder zu Funktion 2
• Technischer Support-Links

Offensichtlich sind diese beiden Dokumentationstypen eng miteinander verwandt und folgen einer ähnlichen Struktur. Dies bedeutet, dass Produkt- und Software-Teams viel voneinander lernen können und großes Potenzial haben, wenn sie bei der Dokumentation zusammenarbeiten.

Produkt- und Softwaredokumentationsteams können sich ergänzen¶

Es gibt deutliche Ähnlichkeiten zwischen Produkt- und Softwaredokumentation. Dies wirft die Frage auf: Können Produkt- und Software-Teams zusammenarbeiten?

Ja, sie können und sollten es!

Software-Teams verstehen den technischen Fachjargon und die zugrundeliegenden Technologien. Produkt-Teams verstehen, was Benutzer sehen, wollen und brauchen – die Benutzererfahrung. Autor:innen von Softwaredokumentation können detaillierte technische Informationen liefern, und Autor:innen von Produktdokumentation können die technischen Details für ein Laienpublikum vereinfachen.

Stellen Sie sich vor, Sie müssten etwas in einfachen Worten erklären, ohne das nötige Verständnis zu haben, um es verständlich zu formulieren. Genau das passiert, wenn Produktdokumentation vor der Softwaredokumentation erstellt wird.

Was ist Quantenmechanik? Wahrscheinlich denken Sie zuerst an Schrödingers Katze! Aber was hat Quantenmechanik mit Katzen zu tun? Für den Benutzer ist das nicht wichtig. Für einen Physiker bedeutet es alles.

Mit Softwaredokumentation beginnen, mit besserer Produktdokumentation in Docsie enden¶

Zusammenfassend gibt es viele Vorteile, wenn Softwaredokumentation als Vorlage für die anschließende Produktdokumentation dient. Softwaredokumentation sollte als zentrale Informationsquelle für IT-Mitarbeiter:innen und Autor:innen von Produktdokumentationen fungieren. Nach ihrer Erstellung verfügen die Autor:innen von Produktdokumentationen über die nötige Klarheit und das Verständnis, um benutzerfreundliches Wissen für Kund:innen zu vereinfachen und zu teilen, mit technischer Anleitung für Korrekturlesen und Qualitätssicherung.

Einfach ausgedrückt: Mit hervorragender Softwaredokumentation als Basis können Ihre Autor:innen noch bessere Produktdokumentation erstellen!

Beginnen Sie mit der Erstellung von Dokumentation, die Ihren Kund:innen hilft, mehr zu erreichen. Melden Sie sich für unseren Startup-Plan (für immer kostenlos!) an und bieten Sie mit Docsie Dokumentationsfreude!