Das Benutzerhandbuch ist das “Buch”, in dem die Bedienung der Software für die Nutzer beschrieben ist. Es ist Teil der Produktdokumentation. Projekte planen die Aktualisierung des Benutzerhandbuches gerne so spät wie möglich. In Projekten mit klassischen Vorgehensmodell  (“Wasserfall”) ist sowas noch einigermaßen gut planbar. Mit den agilen Methoden in den Projekten ergibt sich das Problem, dass am Ende des Sprints auch das Benutzerhandbuch fertig sein muss. Das ist meiner Ansicht nach nur schwer leistbar, weil der Großteil der Arbeit in der Gestaltung des Inhaltes liegt – fehlerfreie Inhalte vorausgesetzt. Oft ist die Gestaltung des Benutzerhandbuches und die Art der Veröffentlichung an Vorgaben des Unternehmens gebunden. Es ist auch schwer vorstellbar, dass jedes cross-funktionale Team die Rolle des technischen Redakteurs besetzen kann, wie es für ein professionelles Handbuch notwendig ist.

Im Zusammenhang mit der Spezifikation von Benutzeroberflächen der Anwendung unterscheiden wir Layouts und Manuals. Beide Artefakte haben das Ziel, die Benutzeroberfläche zu beschreiben.

In einem Manual beschreiben wir die Verwendung der Benutzeroberfläche, also das gewünschte fachliche Verhalten aus Sicht der Nutzer. Manuals sind als ideal geeignet, um daraus Testfälle abzuleiten. Aus diesem Grund werden während der Realisierung einer Benutzeroberfläche – hier verwenden wir die Layouts – für den Test bereits die Manuals erstellt. Wir legen für jeden Anwendungsfall, der durch die Akzeptanzkriterien einer User-Story gefordert wird, ein Manual an und beschreiben dort aus Sicht des Nutzers die besonderen Randbedingungen für die Verwendung der Benutzeroberfläche.

Motivation

Der Aufbau eines Manuals unterscheidet sich wesentlich von einem Layout. Eine einigermaßen komplexe Benutzeroberfläche bietet eine Vielzahl möglicher Anwendungsfälle, die sich durch unterschiedliche Eingaben und Beschränkungen bei der Eingabe unterscheiden. Um die Erfassung dieser Anwendungsfälle effizient zu gestaltet, beschreiben wir jeden Anwendungsfall separat in einem Manual.

Ein Manual kann leicht in das endgültige Benutzerhandbuch übernommen werden. Ein Manual stellt sozusagen den Entwurf des Benutzerhandbuches dar.

Ein Manual können wir sinnvoll und effizient erst fertigstellen, wenn eine erste Version in der Software realisiert wurde. Der Autor eines Manuals benötigt die Möglichkeit, die Anwendungsfälle der Benutzeroberfläche in der Anwendung durchzuführen.

Am Ende des Sprints haben die Entwickler das Layout der Benutzeroberfläche realisiert und die Tester mit der Erstellung der Testfälle die Manuals dazu fertiggestellt.  Manuals werden nur für Layouts vom Typ Client, Window oder Dialog erstellt. Für untergeordnete Layouts vom Typ Panel, Prompt oder Widget erstellen wir keine Manuals. Der Grund ist, das diese Layouts das Ziel der Wiederverwendung unterstützen. Wiederverwendung bedeutet aber, dass die gleiche Software-Komponente in unterschiedlichen Kontexten in der Anwendung genutzt wird. Eine einheitliche Beschreibung im Sinne eines Benutzerhandbuches ist praktisch unmöglich.

Die Kombination aus Layout und Manuals ergibt eine vollständige Beschreibung der Struktur und des Verhaltens der Benutzeroberfläche. Die Manuals sind außerdem ein gut gepflegter Entwurf des Benutzerhandbuches. Gut gepflegt, weil die Manuals während des Sprints erstellt und verwendet wurden und damit Fehler durch das Feedback der Tester weitestgehend gefunden und beseitigt wurden.

Die Erstellung des Benutzerhandbuches am Ende des Releases wird dadurch stark vereinfacht und auf redaktionelle Arbeiten (z.B. die rechtschreibliche, stilistische, grammatikalische und inhaltliche Verbesserung der Texte) und die optische Gestaltung reduziert. Die Inhalte sind ja bereits als Fragmente in Form der Manuals vorhanden. Ein ganz klares Plus für die Qualität des Benutzerhandbuches.

Zur Illustration des Textes in einem Manual verwenden wir ausschließlich Screenshots aus der Anwendung. Wir gehen hier bewusst das Risiko ein, dass sich das Mockup im Layout und der Screenshot im Manual unterscheiden. Abweichungen stellen immer irgendeine Art von Fehler dar.

  • Ist es eine falsche Realisierung des Layouts durch den Entwickler, dann erstellen wir einen Defekt zur Korrektur der Software.
  • Eine fehlerhaftes Mockup kann durch nachträgliche Änderungen während der Realisierung entstehen, wenn das Feedback des Entwicklers nicht eingearbeitet wurde.

Definition

Beschreibung

Ein Manual beschreibt die Verwendung der Anwendung aus Sicht der Nutzer. Es ist Teil der Produktdokumentation, muss aber nicht zwingend Teil der Systembeschreibung sein. Oft werden Manuals bewusst in einem getrennten Bereich des Wiki gepflegt, damit die später stattfindende Ausarbeitung des endgültigen Benutzerhandbuches außerhalb des Entwicklungsprozesses besser unterstützt wird.

Das bedeutet, dass der Nutzer eine vollständige Beschreibung zu jedem Anwendungsfall benötigt. Und genau dieser Anspruch wird durch die Manuals gut unterstützt. Zur Reduktion der Komplexität der Beschreibung wird für jeden Anwendungsfall, der mit der Benutzeroberfläche durchgeführt werden kann, ein eigenes Manual angelegt. Zur Illustration des Textes in einem Manual verwenden wir ausschließlich Screenshots aus der Anwendung.

Struktur

Der Aufbau eines Manuals kann nicht festgelegt. Die Struktur orientiert sich am Zielformat des Benutzerhandbuches. Im Zusammenhang mit dem Manual verfolgen wir die strikte Trennung von Inhalt (=Manual) und Präsentation (Benutzerhandbuch).