Softwaredokumentation in der heutigen Welt schnelllebiger Softwareentwicklungsprozesse und agiler Vorgehensmodelle ist eine Herausforderung, wenn wir nicht wissen, wie wir weg kommen von der klassischen Welt der Softwaredokumentation. Weg von mehreren hunderten Seiten langen Installationsanleitungen, Benutzer- oder Administrationshandbüchern im Buchformat, bereitgestellt als PDF.

Damit eine Information auffindbar, hilfreich und zugänglich ist, so wie die Norm für Softwaredokumentation ISO/IEC/IEEE 26514 die Qualitätskriterien einer anleitenden Information für User:innen beschreibt, muss diese genau dort stehen, wo nutzende Personen diese erwarten.

Weiter muss die Information richtig, verständlich und so strukturiert sein, dass nicht nur die Information selbst leicht erfasst werden kann, sondern auch ihre Funktion (z.B. eine Schaltfläche zu betätigen oder vor einer Gefahr zu warnen). Wir reden von einer Information, keinesfalls von einem ganzen Handbuch. Damit eine Information, die für Anwendende wertschöpfend ist, bereitgestellt werden kann, braucht es Informationshäppchen. Diese werden genau dort bereitgestellt, wo anwendende Personen die Information erwarten.

Und um passend zur vorweihnachtlichen Zeit zu sein: Du kannst deine Liebsten mit Gutscheinen und damit der ganzen Auswahl des gewählten Stores beschenken… doch wirkliche Freude bereiten eher die kleinen, persönlichen und auf die Vorlieben der einzelnen Person angepassten Geschenke vom Herzen, nicht wahr? Mach es also für deine User:innen, wie für deine Liebsten… schenke im Hilfefall einfach Topics… kleine, personalisierte und auf die Bedürfnisse angepasste Informationshäppchen – die machen Freude und steigern die UX. Und als kleines Geschenk für dich, haben wir hier zusammengeschrieben, was denn diese „Topics“ überhaupt sind – lies gerne rein!

 

Inhalt

Was ist ein Topic in der Softwaredokumentation?

Wie so oft, gilt auch hier wieder, ein Blick in die Normenwelt lohnt sich. Die wichtigsten Normen für die Softwaredokumentation sind:

  • DIN EN IEC/IEEE 82079-1:2021-09 „Erstellung von Nutzungsinformationen (Gebrauchsanleitungen) für Produkte – Teil 1: Grundsätze und allgemeine Anforderungen“
  • ISO/IEC/IEEE 26514:2022-01 „System- und Software-Engineering – Design und Entwicklung von Informationen für Anwender“

Während erstere branchenübergreifend als Horizontalnorm für die Technische Kommunikation fungiert, fokussiert sich die Norm 26514:2022-01 speziell auf den Bereich der Softwaredokumentation und erweitert damit die 82079 um die „Spezialitäten“ von Informationsprodukten rund um Software. Beide definieren ein Topic, sinngemäß übersetzt, als

„Kohärenten Teil eines Informationsproduktes mit einer Überschrift, der ein einzelnes Thema abhandelt.“

Ein Topic ist also eine kleine Informationseinheit, die ein Thema beschreibt und so viel information enthält, dass das Topic unabhängig von anderen Informationseinheiten verwendet werden kann. Ein gutes Topic ist dabei immer aus Sicht der Anwender geschrieben und widmet sich, je nach Topic-Typ, folgenden Kernfragestellungen:

  • Wer ist die nutzende Person, die diese Information braucht?
  • Welche Information braucht die nutzende Person?
  • Wann braucht die nutzende Person oder Personengruppe diese Information?
  • Wo (Medium) erwartet die nutzende Person diese Information?

Die Herausforderungen in der Praxis: Häufig wird die erste Frage nicht gründlich genug beleuchtet, weshalb die letzte Frage garnicht erst zuverlässig beantwortet werden kann.

Je gründlicher du dich diesen Fragestellungen widmest, desto besser kannst du zielgerichtete Informationen bereitstellen – bis hinein in das Produkt als Labeltext, Platzhalter, Tooltip o.ä. In diesem Falle sprechen wir dann von Microcopy – den GUI-Texten, die durch UX-Writer im UX-Writing-Prozess erstellt werden.

 

Welche Eigenschaften haben Topics?

Ein Topic ist in sich abgeschlossen

Ein Topic beantwortet vollständig eine Kernfrage und kann für sich alleine stehen. Ein Topic benötigt i.d.R. keine vorangestellten und nachgelagerten Informationen, um einen Sachverhalt zu verstehen.

Ein Topic ist konkret und erfüllt einen bestimmten Zweck

Damit diese Eigenschaft überhaupt erfüllt werden kann, brauchst du eine sehr konkrete Vorstellung davon, für welche Zielgruppe du schreibst und wobei diese nutzenden Personen dein Topic heranziehen werden. Erst wenn du deren Erwartungen an den Inhalt erfüllst, erfüllt dein Topic einen spezifischen Zweck – nämlich bei genau dieser Anforderung zu helfen.

Ein Topic definiert seinen Kontext

Nutzende Personen übernehmen gewohntes Verhalten aus dem Web in deine Online-Hilfen und erwarten häufig, dass diese funktionieren, wie Suchmaschinen, Webseiten und Blogs, die im Internet verfügbar sind. Das hat nicht selten zur Folge, dass Online-Hilfen reichlich verlinkt und mit starken Suchfunktionen ausgestattet werden.

Die Folge: Jedes Topic kann durch die lesenden Personen direkt angesprungen werden, ohne dass diese vorangestellten Inhalte kennen. Bedenke das beim Erfassen deiner Topics und stelle immer sicher, dass dein Topic seinen eigenen Kontext für den Inhalt abgrenzt. Worum geht’s hier? Wo befindet sich die nutzende Person und was lernt oder erreicht sie, wenn diese deine Inhalte erfasst hat?

Ein Topic ist immer für eine bestimmte Zielgruppe bestimmt

Genaugenommen meine ich damit, dass ein Topic immer eine Gruppe von lesenden Personen adressiert, die ähnliche Funktionen im Produkt durchführen und/oder einen ähnlichen Wissensstand haben. Mische daher inhaltlich nicht, was nicht zur gleichen „Gruppe“ gehört. Halte das Niveau „stabil“ (fach)sprachlich, inhaltlich und rollenbasiert.

Ein Topic kommuniziert benötigtes Vorwissen transparent

Damit ein Topic konkret werden und einen bestimmten Zweck erfüllen kann, ist es wichtig, dass du bestimmte Vorqualifikationen deiner Zielgruppen voraussetzt. Denn sonst kommst du ganz schnell in die Verlegenheit, in jedem Topic jedes potenziell fehlende Wissen in einem Topic zu beschreiben und wenn du das anfängst, könnte dein ganzes Handbuch ein einzelnes Topic sein, nicht wahr?

Grenze also bewusst ab, was zu diesem einen Thema gehört und was nicht. Von den ausgegrenzten Inhalten… welche davon sind z.B. Voraussetzungen für deinen Topic? Welche werden für das Verständnis deines Topics benötigt und müssen vorab bekannt sein?

Ein Topic entspricht immer einem standardisierten Topic-Typ

Jedes Topic sollte einem klaren Topic-Typ entsprechen. Hierbei ist es zweitrangig, ob es sich um bekannte Topic-Typen aus bekannten XML-Standards handelt, oder ob du eigene Topic-Typen definiert hast. Wichtig ist nur, dass jeder Topic-Typ, den du einsetzt, einer standardisierten Struktur folgt und lesende Personen einen Topic dadurch direkt einem der bestehenden Topic-Typen zuordnen können.

 

Welche Topic-Typen gibt es in der Softwaredokumentation?

Damit du Informationseinheiten bereitstellen kannst, sodass nicht nur die Informationen selbst leicht erfasst werden können, sondern auch ihre Funktionen (z.B. eine Schaltfläche zu betätigen oder vor einer Gefahr zu warnen), haben sich in der Praxis einige Topic-Typen etabliert, die für viele Anwendungsfälle sehr gut passen. Unterschiedliche XML-Standards wie z.B. DITA oder DocBook definieren ein- oder mehrere Topic-Typen mit unterschiedlichen Topic-Strukturen. Im Wesentlichen gibt es, z.B. bei der Darwin Information Typing Architecture (DITA), einige wenige Grund-Topic-Typen, wie z.B.:

  • Informationen zum Beschreiben komplexer Konzepte
  • Informationen zum Anleiten bei Handlungen
  • Informationen zum Nachschlagen von z.B. Parametern
  • Informationen zum Beseitigen von Fehlerfällen

Jeder Topic-Typ folgt dabei einer klaren Struktur, die ihn durch seine Charakteristiken als solchen identifiziert. Auch Topic-Typen für Lerninhalte oder Glossareinträge sind gängig. Aber auch eigene Spezialisierungen bekannter Topic-Typen aus freien Standards oder das Erstellen eigener Topic-Typ-Definitionen ist denkbar, wenn die Umstände es in deinem Kontext erfordern sollten.

Fazit

Wer heute eine Softwaredokumentation zielgerichtet bereitstellen will, die die User-Experience der Softwareanwender ganzheitlich positiv beeinflusst, die genauso modern ist, wie das gute Softwareprodukt selbst, der kommt kaum an der topicorientierten Erfassung von Inhalten vorbei. Gute User-Assistenz, also eine moderne Softwaredokumentation, braucht zielgruppengerechte Bereitstellung kleiner Informationseinheiten über alle Berührungspunkte im und um das Produkt hinweg.

Einfacher gesagt als getan, denn genau dieses „zerlegen“ von Unmengen an Inhalten und Bestandsinformationen benötigt eine sorgfältige Planung in der Standardisierung, Modularisierung und auch der Erfassung der Inhalte selbst. Kommen dann auch noch mehrere Autoren ins Spiel, wird Konsistenz, Terminologie und Qualitätssicherung noch wichtiger. Das Gute für dich: Wir haben in unseren Seminaren die volle Ladung Wissen, Methoden und Übungen, damit du dein Knowhow rund um Softwaredokumentation auf das nächste Level bringen kannst. Schau gerne mal rein: