Normenreihe 2651x für Software-Dokumentation

Für Software-Dokumentation gibt es nur wenige konkrete Vorgaben und Normen. Die Handbuch Experten stellen Ihnen hier eine Normenreihe speziell für Software und deren Informationsbedarfe vor.

Die Einhaltung von Normen ist keine gesetzliche Vorgabe. Ihre Anwendung erfolgt immer freiwillig. Normen bieten jedoch den Vorteil, dass sie üblicherweise den Stand der Technik widerspiegeln. So machen Sie beispielsweise Produkte und Prozesse vergleichbar, Optimierungspotential oft erst sichtbar und ermöglichen eine leichtere und bessere Zusammenarbeit. Dies trifft nicht nur auf das eigene Unternehmen zu, sondern auch für alle anderen am Markt. Auf diese Weise kann besser analysiert werden, wie andere Unternehmen vorgehen und auch was die eigenen Kunden aufgrund ihrer Erfahrungen erwarten.

Für den Informationsbedarf bei Software, auch in einer agilen Entwicklungsumgebung, bildet die Normenreihe 26511 bis 26515 ein zentrales Nachschlagewerk.
Am Untertitel der jeweiligen Norm lässt sich die primäre Zielgruppe bereits gut ableiten:

  • 26511: Personen in Leitungsfunktionen, Manager
    • Prozess aus Sicht des Managements hinsichtlich seiner Pflichten, Aufgaben und erwartete Ergebnisse
  • 26512: Personen, die Dokumentationsleistungen einkaufen, und Lieferanten
    • Vorgaben und Regeln für die Zusammenarbeit zwischen Auftraggebern und Lieferanten
  • 26513: Personen, die Prüfungen vornehmen oder Gutachten erstellen
    • Vorgaben für Prüfungen und Usability-Tests
  • 26514: Informationsentwickler, Technische Redakteure
    • Standardisierungsansatz und Vorgaben für Informationsprodukte
  • 26515: Personen, die in agilen Umgebungen arbeiten
    • Vorgaben für Erstellen und Verwalten von Informationen innerhalb einer agilen Entwicklungsumgebung

Für Technische Dokumentation interessant

Im Hinblick auf Software-Dokumentation sind vor allem die letzten beiden Normen aus der Reihe interessant. In der 26514 liegt der Fokus in erster Linie auf dem Informationsbedarf für Endanwender, von der Planung bis zur Auslieferung und dem Ausrollen von Updates. Es werden Anforderungen an Layout, Struktur und Inhalt gennant. Zudem enthält der Anhang praktische Checklisten.

Die Norm ist "Tool-neutral" gehalten. Sie empfiehlt lediglich die Nutzung eines CMS mit Single-Source-Publishing, vergleichbares findet sich in der "klassischen" Norm zur Nutzungsinformation DIN EN 82079-1. Anforderungen an die Personen, die Dokumentation erstellen, werden nicht genannt. Es wird lediglich davon ausgegangen, dass Leser der Norm entsprechende Erfahrung mit Softwareentwicklung und dem Erstellen von Dokumentation haben.

Mit knapp 160 Seiten ist die 26514 eine umfangreiche Norm und enthält dabei vieles, was nicht spezifisch nur für Software relevant ist. Es wird hauptsächlich der Prozess an sich beschrieben: Projektanforderungen und Ziele, Zielgruppenanalyse und Redaktionsleitfaden, Entwicklung und Prüfung der Dokumentation nach dem Redaktionsleitfaden sowie die Publikation und Auslieferung von Produkt und Dokumentation.

In der 26515 liegt der Fokus hingegen vollständig auf der Informationsentwicklung der internen Dokumentation. Es werden Konzepte und Prozessbeschreibungen, die Integration der Informationsentwickler in Sprints und weitere Anforderungen aufgestellt.
Laut der Normenreihe sollte eine umfassende Zielgruppenanalyse erfolgen und alle Informationen auf Rollen und Personas zugeschnitten erarbeitet werden, z. B. nach dem folgenden Schema.

Rollen und deren ZieleBeispiel EinsteigerBeispiel Admin
As a (role), I want (goal), so that I can (business value).Als Einsteiger (Rolle), will ich mich schnell einarbeiten (Ziel), damit ich im Tagesgeschäft flexibel bin (Unternehmenswert).Als Admin (Rolle) will ich vor allem Informationen zu Installation und Einrichtung (Ziel), damit ich die Software bereitstellen kann (Unternehmenswert).

Eine weitere Möglichkeit ist die Informationen als Szenario aufzubereiten.
Admins müssen ggf. Nutzer anlegen und können dafür verschiedene Rechte verteilen.

BenutzerrolleBeispiel für Rechte
AdminBenutzer und Daten anlegen, ändern, löschen
Key UserDaten anlegen, ändern, löschen
AnwenderEigene Daten anlegen, ändern
BetrachterVorhandene Daten einsehen

Oder auch als Use Case können Informationen verständlich an Softwarenutzer weitergegeben werden.

Bei Microsoft Word wäre dies z. B. das Erstellen von Formatvorlagen:

  • Es gibt Absatz- und Zeichenformate
  • Diese unterscheiden sich in ...
  • Sollten verwendet werden für ...

Bei Adobe InDesign könnte dies z. B. die Arbeit mit Musterseiten sein:

  • Wozu anlegen?
  • Welcher Vorteil?
  • Wie einsetzen?

Mit knapp 40 Seiten ist die 26515 kompakt gehalten. Für die externe Dokumentation bietet sie Informationen zum Dokumentationsplan, Informationsmanagement, Beschreibung von Interfaces, Softwarearchitektur und ähnliches. Auch für die Informationsbeschaffung enthält die Norm mögliche Fragen, die Entwicklern gestellt werden können, um die - mindestens von den Entwicklern so eingeordnet - intuitive Software für den Anwender leichter zugänglich zu machen.

Ist Ihre Software hochkomplex oder multifunktional und Ihre Kunden verstehen gar nicht, was sie alles kann?
Dann sollten Sie Ihren Kunden eine gute Anleitung an die Hand geben. Profitieren Sie von unserer Erfahrung.

Einschränkungen

Die Normenreihe kann verständlicherweise nicht auf alles eine Antwort liefern. Dennoch bleiben auch einige Fragen offen, die für Software-Dokumentation besonders relevant sind.
So kann die Norm 26514 z. B. keine Lösungen anbieten, die im Zusammenhang mit komplexen Softwareprodukten aufkommen, wie Systemsoftware.

Auch Vorgaben für die notwendige Qualifikation von Informationsentwicklern finden sich nicht. Hier wäre eine Möglichkeit, die 82079-1 parallel zur 26514 heranzuziehen.

Kommende Neuerungen in 2022

Die 26514 befindet sich aktuell in der letzten Phase ihrer Überarbeitung. Die Veröffentlichung der neuen Version ist für Anfang 2022 geplant. Dabei kommen einige neue und hilfreiche Teile hinzu, die wir Ihnen als Ausblick ebenfalls kurz vorstellen möchten.

Bisher war die Strukturierung der Benutzerinformationen in Topics nur eine Empfehlung. Zukünftig soll diese zwingend vorgeschrieben werden, d. h. die Norm wird Vorgaben an die Basisstruktur (Anleitung, Troubleshooting, etc.) als Topic-Klassen für eine effektive Filterung der Informationen enthalten.

Auch unterschiedliche Arten von Dokumentation werden nun aufgenommen. Für Software-Produkte sind Online-Hilfen eher die Norm als die Ausnahme, wobei die digitale Nutzung sich von der gedruckter "klassischer" Handbücher unterscheidet. Inhalte kommen hier erfahrungsgemäß verstärkt von der Seite der Nutzer, z. B. über Wikis, Foren und Kommentare. Daher werden in der Norm auch FAQ (Häufig gestellte Fragen) aufgeführt, diese sind bisher in keiner anderen Norm in dieser Form und Ausführlichkeit enthalten. FAQs sind für Software unglaublich wichtig und können z. B. auch gut als erste Basis für interaktiven Content wie Chatbots verwendet werden. Chatbots sollten immer eine zielgerichtete Unterhaltung mit den Usern führen. Zum Thema Voice-Response und Chatbots gibt es allerdings noch zu wenig Praxiserfahrung. Dieser Teil ist daher noch nicht vollständig ausgearbeitet, gilt aber bereits als wegweisendes Signal für die Zukunft.

Technische Redakteure werden in der Norm künftig auch als "User Assistant Developer" bezeichnet und die Hilfestellung für den Nutzer sollte man sich zu Herzen nehmen.
Gerade bei der Chatbot-Entwicklung zeigt sich, dass Informationsentwicklung nicht nur das Aufschreiben von Informationen ist, sondern dass vor allem der Bedarf der Zielgruppe erfasst und dann entsprechende Antworten und Informationen angeboten werden müssen.

Hinzugekommen ist auch eine Referenz auf die DIN EN IEC/IEEE 82079-1, die zentrale Norm für Technische Dokumentation.

Erstmalig werden auch Ziele für Benutzerfreundlichkeit aufgenommen. Explizit bedeutet dies, dass die Usability des Produkts auch die Usability der Informationen für die Nutzung beinhaltet. Die technische Dokumentation gehört zum Produkt und muss damit auch Teil von Usability Tests sein – nicht erst am Ende oder im Nachgang.

Fazit: Normen sind nicht nur abstrakt, sondern geben eine gute Hilfestellung, um am Puls der Zeit zu bleiben

Normen machen die Erstellung Technischer Dokumentation deutlich einfacher, effektiver, effizienter.

Ein typisches Beispiel ist die Beschreibung einer Software-Oberfläche. Hier finden sich oft Fehler, weil die Art der Formulierung nicht an der Norm orientiert ist.

Schlecht sind Formulierungen, wie "Klicken Sie oben auf das grüne …".
Dies kann beispielsweise problematisch sein, wenn User farbfehlsichtig sind (Rot-Grün-Schwäche usw.) oder die Farbdarstellung am Bildschirm sich stark von der eigenen unterscheidet und das Objekt "…" gar nicht grün aussieht.

Eine bessere Lösung bietet die Verwendung von Namen und Bezeichnungen, die auch in der Software für "…" verwendet werden, alternativ kann ggf. ein konkretes Icon dafür entwickelt und verwendet werden.

Ihre Entwickler sind mehr mit der Software-Erstellung beschäftigt, als dass sie Zeit für Benutzerinformationen hätten?
Unsere erfahrenen Redakteure wissen, was Software-Anwender brauchen: eine klare Linie für den Durchblick.
Ihr Ansprechpartnerin Anna Lehmann
Anna Lehmann

Lassen Sie uns über Ihr Projekt sprechen.