Das sind die Grundlagen von Softwaredokumentation

Mal eine ganz persönliche Frage: Verlierst du den Durchblick im Software-Dschungel? Keine Sorge, Hilfe naht! Software- und IT-Service-Anleitungen können nämlich ziemlich unterschiedlich sein, was die Qualität angeht. Kennst du das? Bedienungsanleitungen, die so allgemein gehalten sind, dass sie für niemanden wirklich hilfreich sind? Leider gibt es solche Anleitungen viel zu oft. Aber das muss nicht sein!

Wie hebst du deine Anleitungen aus der Masse heraus?

Möchtest du, dass deine Anleitungen herausstechen? Dann lies weiter! Hier bekommst du die Grundlagen für richtig gute Softwareanleitungen und erfährst, welche Normen und Richtlinien wirklich relevant sind.

Was macht eine gute Technische Dokumentation aus?

Eine gute Technische Dokumentation hilft den Nutzer:innen, ihre Aufgaben effizient zu erledigen. Sie ist leicht zu finden, einfach zu lesen und vor allem: hilfreich! Aber wie legst du den Grundstein für maßgeschneiderte User-Assistance? Eine gründliche Analyse des aktuellen Zustands und des Informationsbedarfs deiner Nutzerschaft ist der erste Schritt.

Interne oder externe Dokumentation – Was ist was?

Bevor du loslegst, solltest du unbedingt wissen: Es gibt einen Unterschied zwischen interner und externer Softwaredokumentation. Aber was gehört zu welcher Kategorie?

Was ist interne Softwaredokumentation?

Interne Softwaredokumentation ist für den eigenen Gebrauch gedacht. Sie dokumentiert deine internen Aufgaben, Entwicklungsschritte und Prozessabläufe. Warum ist das wichtig? Damit auch in der Zukunft alle Entscheidungen nachvollziehbar bleiben und Wissen im Unternehmen erhalten bleibt – selbst bei Personalwechseln.

Welche Beispiele gibt es für interne Softwaredokumentation?

Einige Beispiele gefällig? Hier sind ein paar typische interne Dokumentationen:

• Projektdokumentation (Pflichtenheft, User-Stories, Backlogs)
• Systemdokumentation (Code-Kommentare, UI-Design)
• Schnittstellendokumentation (API, GUI)
• Testdokumentation und Prozessdokumentation

Warum solltest du dir die Mühe machen, intern zu dokumentieren?

Du fragst dich vielleicht, warum du in Zeiten schneller Releases überhaupt intern dokumentieren solltest. Gute Frage! Hier sind ein paar Gründe:

• Wissen konservieren für zukünftige Weiterentwicklungen
• Qualitätssicherung und Einhaltung von Normen
• Optimierung von Prozessen und Abläufen
• Abfangen von Personalausfällen
• Langfristig Zeit und Geld sparen

Was passiert, wenn du nicht dokumentierst?

Wenn du auf die Dokumentation verzichtest, stehst du schnell vor einem Problem: Niemand weiß mehr, warum bestimmte Entscheidungen getroffen wurden. Stell dir mal diese Fragen:

• Welche Entscheidung musste überhaupt getroffen werden?
• Warum wurde genau diese Entscheidung getroffen?
• Gab es andere Lösungen, und warum wurden sie verworfen?

Was ist externe Softwaredokumentation?

Kommen wir zur externen Softwaredokumentation. Diese Dokumentation richtet sich an die Endnutzer:innen und beschreibt, wie die Software funktioniert. Ziel ist es, den Nutzer:innen zu helfen, die Software problemlos zu bedienen. Die Dokumentation ist stark auf die Zielgruppe zugeschnitten.

Was muss eine gute externe Softwaredokumentation erfüllen?

Wenn du deine Softwaredokumentation erstellst, achte darauf, dass sie folgende Anforderungen erfüllt:

• Vollständig, sachlich korrekt und aktuell
• Unterstützt eine intuitive Anwendung
• Hilft den Nutzer:innen bei der Lösung ihrer Aufgaben
• Bietet eine durchdachte Navigation und Suchfunktion
• Verwendet eine konsistente Sprache, die für die Nutzer:innen verständlich ist
• Berücksichtigt relevante Normen und Anforderungen
• Ist nicht nur als PDF, sondern auch kontextsensitiv verfügbar
• Bietet idealerweise eine Feedback- und Auswertungsfunktion

Wie passt die agile Entwicklung zur Dokumentation?

Agile Entwicklung ist heutzutage überall ein Thema. Aber was bedeutet das für die Dokumentation? Agil bedeutet nicht, dass die Informationsprodukte selbst agil sind, sondern dass ihr Entstehungsprozess es ist. In einem agilen Umfeld läuft die Entwicklung und Dokumentation oft parallel ab, was viele Vorteile, aber auch Herausforderungen mit sich bringt.

Wie dokumentierst du agil?

In der agilen Dokumentation wird in kürzeren Intervallen gearbeitet, oft in sogenannten Sprints. Pro Sprint wird eine Funktionalität der Software umgesetzt und dokumentiert. Dabei ist es wichtig, regelmäßig Feedback einzuholen und die Dokumentation stetig anzupassen. So bleibt die Dokumentation immer auf dem neuesten Stand und entspricht dem aktuellen Entwicklungsstand der Software.

Welche Normen solltest du kennen?

Es gibt zwar keine konkreten gesetzlichen Vorgaben für Softwaredokumentation, aber einige Normen solltest du kennen:

• ISO IEC IEEE 26511 bis 26515 (verschiedene Aspekte der Benutzerinformation)
• ISO IEC IEEE 15289 (Inhalt von Lebenszyklus-Informationsartikeln)
• IEC/IEEE 82079-1 Ed. 2 (allgemeine Grundsätze für Gebrauchsanleitungen)

Diese Normen geben dir wertvolle Hinweise, wie du deine Softwaredokumentation verbessern kannst.

Das war ein erster Einblick in die Welt der Softwaredokumentation.