Wie muss eine „gute“ Dokumentation formuliert werden? (Gutes Anforderungsmanagement, Teil 4)

In diesem Beitrag möchte ich zunächst näher auf das Formulieren von Anforderungen eingehen. Wir setzen die Serie der Fallen fort mit „Falle 5“. Dort dreht sich alles um unverständliche Formulierungen und deren Konsequenzen für das Anforderungsdokument. Gegen Ende steht der Findungsprozess von Anforderungen und der Einfluss der agilen Methoden im Mittelpunkt.

„Anforderungen dokumentieren – das ist doch ein Kinderspiel“, sollte man meinen. Dem ist aber nicht so, zumindest wenn man sich die landläufige Meinung anschaut, die zu bestehender Dokumentation existiert. Mehrheitlich besteht die Meinung, dass Anforderungsdokumente

  • nicht aktuell sind,
  • nicht von anderen außer dem Verfasser verstanden werden,
  • nicht die besonders kniffligen Sonderfälle enthalten und
  • schlecht strukturiert sind, sodass man nie die richtige Stelle findet.

„Ach, und überhaupt sei die Telefonliste der Ansprechpartner eh am wichtigsten.“

Tja, was bedeuten diese Aussagen für Anforderungsdokumente? Kurz gesagt: Viele Dokumentationen werden gar nicht erst gelesen!

Für uns als Requirements Engineer bedeutet das, dass wir eine Form der Dokumentation finden müssen, die akzeptiert und „konsumiert“ wird. Daher zeige ich, welche Möglichkeiten uns zur Verfügung stehen.

Grundsätzlich gilt, dass zur Dokumentation eine standardisierte Art der Gliederung verwendet werden sollte. Vorgehensmodelle wie RUP oder das V-Modell schreiben bzw. schlagen auch für die Dokumentation Richtlinien vor. Weiter bieten die IEEE 830 (Software Requirements Specification), ein vom IEEE veröffentlichter Standard zur Spezifikation von Software, und Volere beispielsweise Templates an, die zur Kommunikation und Verwaltung von Anforderungen genutzt werden können. Volere kann universell eingesetzt werden und ist nicht beschränkt auf bestimmte Entwicklungsmethoden. Speziell für Software-Architektur-Dokumentation hat sich arc42 einen Namen gemacht und wird mittlerweile häufig in IT-Projekten eingesetzt.

Ob Sie eines der dieser Templates nutzen, ist Ihnen überlassen. Viel wichtiger ist, dass Sie sich auf eine einheitliche Gliederung verständigen können.

Dokumentation in Form von Prosatext – ist das sinnvoll?

Die meisten Anforderungsdokumente sind in Prosatext verfasst. Dies hat Vor- aber auch Nachteile.

Vorteile
Prosatexte werden in der Regel von allen Beteiligten verstanden. Kein Stakeholder muss neue Notationen lernen, um das Anforderungsdokument zu verstehen. Prosatext kann darüber hinaus universell und themenunabhängig eingesetzt werden.

Nachteile
Je nach Kontext können mehrere Interpretationen möglich sein, da z.B. Mehrdeutigkeiten im Text enthalten sind. Sie schleichen sich schnell ein, da wir schon in der Schule dazu motiviert wurden „Wortvariationen“ zu verwenden. So haben wir beispielsweise gelernt,  nicht immer das Wort Möglichkeit, sondern auch Chance oder Gelegenheit zu verwenden.

Weiter ist es für manche Sachverhalte gar nicht günstig Prosatext zu verwenden – oder haben Sie schon einmal versucht, eine Anleitung zum Papierflieger-Bauen nur mit Hilfe von Worten zu formulieren? Wahrscheinlich nicht, denn eine Grafik ist in diesem Fall wesentlich ausdrucksstärker.

Nun aber zurück zu unseren „Fallen“.

Falle 5: Unverständliche Formulierungen

Um diesen Punkt zu verdeutlichen, zeige ich Ihnen ein Beispiel:

Funktionalität
… In einer „Übersicht“ über alle noch nicht zugeordneten Geschäftspartner werden alle Geschäftspartner aller Mandanten ungleich Mandant 0 angezeigt, die bisher keinem Geschäftspartner im Mandanten 0 zugeordnet wurden. …

Fällt Ihnen etwas auf? Ja genau, die Satzstruktur ist viel zu komplex und somit unverständlich. Auch die drei Verneinungen „nicht zugeordnete“, „ungleich Mandant 0“ und „keinem Geschäftspartner“ erschweren das Verständnis erheblich.

Aber neben der komplizierten Satzstruktur ergeben sich noch weitere inhaltliche Fragen – und hier kommen wir auch schon zu Falle 6.

Falle 6: Versteckte Annahmen

Es  stellen sich die sog. W-Fragen, die, wie hier, sehr häufig unbeantwortet bleiben:

  • Was ist die „Übersicht“?
  • Wo befindet sich diese?
  • Wer ordnet etwas zu dem Mandanten 0 zu?
  • Was ist Mandant 0?
  • Was bedeutet „im Mandanten“ sprachlich?

Falle 6 wird unter Umständen noch verstärkt, und zwar durch den Requirements Engineer selbst. Im Laufe der Zeit läuft der RE Gefahr, „betriebsblind“ zu werden und so tief in der Thematik zu stecken, dass viele Dinge als selbstverständlich angenommen und nur unzureichend oder auch gar nicht dokumentiert werden.

Um versteckten Annahmen von vornherein entgegenzuwirken, bietet es sich an, auf bestehende Regelwerke/Vorschläge zurückzugreifen, die bei der Formulierung helfen, so z.B. das Sophist-REgelwerk.

Es besagt, dass sich im Zusammenhang mit bestimmten Mustern bestimmte W-Fragen ergeben:

  • Passiv unterschlägt den Täter
    • Beispiel: Ein Auftrag kann storniert werden.
    • W-Fragen: Von wem? Wann?
  • Analyse des Prozesswortes
    • Beispiel: Das System zeigt das Ergebnis nach der Berechnung an.
    • Das Prozesswort ist anzeigen. W-Fragen: Wem? Wie? Wann? Warum? …
  • Vergleiche und Steigerungen
    • Beispiel: Die GUI muss schneller reagieren als beim Altsystem.
    • W-Frage: Um wie viel schneller?

Die vollständige Liste können Sie unter folgendem Link anschauen: https://www.sophist.de/anforderungen/requirements-engineering

Zur Dokumentation haben sich besonders sog. Satzschablonen bewährt – dies mag erst einmal nicht besonders elegant oder literarisch anspruchsvoll wirken, da die Sätze sehr einfach konzipiert sind. Als Beispiel für solch eine Satzschablone habe ich die User-Story gewählt:

As a <role> I want <goal/desire> so that <benefit>

Als ein Autor will ich meine Präsentation speichern können, damit ich nicht noch einmal alles eingeben muss

Ein Ziel dieser Satzschablone ist insbesondere die Beantwortung des Geschäftswerts, der durch den Teil nach dem Wort „damit“ beantwortet werden muss. Diese Satzschablone hat sich bei der agilen Vorgehensweise Scrum etabliert, da sich dadurch für das Sprint-Planning eine Priorisierung der User-Storys ableiten lässt.
Selbstverständlich gibt es noch weitere Satzschablonen – diese sollte nur als ein Beispiel dienen.

Im Laufe der Jahre haben sich aufgrund des Schwachpunkts, dass Prosatext zur Dokumentation häufig ungeeignet ist, sog. Domänen-spezifische Sprachen (DSL) entwickelt. Diese ermöglichen es, wesentlich exakter zu spezifizieren. Herausgekommen sind dabei bspw.

  • die Formelsprache zur Beschreibung mathematischer und physikalischer Phänomene,
  • Entity-Relationship-Diagramme zur Datenmodellierung,
  • UML zur Spezifikation von Software,
  • BPML zur Darstellung von Geschäftsprozessen sowie
  • HTML/CSS zur Beschreibung von Websiten.

Es ist offensichtlich, dass diese eindeutiger und aussagekräftiger sind als Prosatexte. Der geübte Leser kann diese Art der Notation sogar häufig schneller verstehen.

Trotz der Vorteile gibt es auch bei diesen Notationen Nachteile, z.B.

  • sind sie nicht universell einsetzbar,
  • die Syntax/Semantik muss vom Leser erst verstanden werden, und
  • es müssen häufig zusätzliche Tools erlernt werden.

Die Vorteile der einen Methode sind die Nachteile der anderen und umgekehrt, sodass sich eine Mischung aus Domänen-spezifischer Notation und Prosatext i.d.R. sehr gut ergänzen. Hier ein Beispiel aus der Mathematik, die sich schon seit langer Zeit dieser Mischung bedient:

Aus jeder nicht-negativen reellen Zahl lässt sich die Wurzel ziehen (Prosa), und genauer mittels DSL:

Wurzel ziehen_mittels DSL


Derjenige, der bereits weiß, was gemeint ist, braucht sich die Formel nicht mehr anzuschauen. Aber für denjenigen, dem dies nicht klar ist, kann die Aussage noch einmal unmissverständlich anhand des formalen Ausdrucks verstehen.

Zusammenfassung: Wie soll ein Requirements Engineer dokumentieren?

  • Achten Sie bei Ihrer Dokumentation auf eine einheitliche, standardisierte Gliederung.
  • Wägen Sie das Für und Wider der Verwendung von Prosatext genau ab. Beachten Sie, dass Prosatext sich nicht zum Beschreiben von allen Dingen eignet. Vor allem bei zeitlichen Abläufen, wie bei Geschäftsprozessen sind Grafiken (BPML, UML) wesentlich anschaulicher.
  • Achten Sie bei Formulierungen auf einen einheitlichen Aufbau. Satzschablonen helfen Ihnen dabei, da durch sie viele wichtige W-Fragen automatisch beantwortet werden.

Wenn Sie diese Hinweise beachten, sind Sie auf einem guten Weg, ein Anforderungsdokument zu verfassen, das sowohl gelesen als auch verstanden wird.

Artikelreihe "Gutes Anforderungsmanagement - sieben Fallen, die ein Reqiurements Engineer kennen und meiden sollte"

Sieben Fallen, die der Requirements Engineer kennen und meiden sollte (Gutes Anforderungsmanagement, Teil 1)
Falle 2: Faule Kompromisse und Falle 3: Designfehler bei Geschäftsmodellen (Gutes Anforderungsmanagement, Teil 2)
Falle 4: Unklare Fachbegriffe und Best Practices (Gutes Anforderungsmanagement, Teil 3)
Wie muss eine „gute“ Dokumentation formuliert werden? (Gutes Anforderungsmanagement, Teil 4)
Acceptance Test Driven Development (Gutes Anforderungsmanagement, Teil 5)

Literatur

Chris Rupp, SOPHIST GROUP Requirements-Engineering und -Management Professionelle, iterative Anforderungsanalyse für die Praxis ISBN: 978-3-446-41841-7

Schreibe einen Kommentar

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.