MIP40 Methoden der Softwaredokumentation

CASE-Tools sind Computerprogramme, die bei der Softwareentwicklung unterstützen. Die Unterstützung erfolgt in den Bereichen Planung und Überwachung von Teilarbeits- schritten, Unterstützung der Entwurfsphase, automatische Umsetzung der Entwürfe in die Datenbank inklusive Prüfung auf Vollständigkeit. Entwürfe können automatisch in lauffähige Programme übertragen werden und auch die Erstellung von Datenstrukturen und Bildschirmmasken ist automatisiert.

Orgware ist eine zusammenfassende Bezeichnung für nicht zur Hard- und Software gehörende Methoden bei der Abwicklung von IT-Projekten. Dazu zählen Sicherheits- konzepte, IT-Dienstanweisungen, Benutzerhandbücher, Aufgabenbeschreibungen, Organisationspläne u.a.

SOPs (Standard Operating Procedures) sind detailliert geschriebene Instruktionen, um einen absoluten Gleichschritt der Performanz in einer spezifischen Situation zu errei- chen. SOPs sind für alle Prozeduren sinnvoll, bei denen potenzielle Gefahr für Gesund- heit und Sicherheit von Menschen bestehen könnte. Sie sind für Regierungsorganisatio- nen sehr hilfreich, um in Notsituationen schnell reagieren zu können und für klinische Forschungseinrichtungen maximale Sicherheit zu gewährleisten

DONALD E.KNUTH von der Stanford University veränderte mit seinem Konzept des „literate programming“ die traditionelle Herangehensweise der Softwareentwicklung und Softwaredokumentation. Üblicherweise beschäftigten sich Programmierer mit der Formulierung von Instruktionen an den Computer. Neu war an diesem Ansatz das Selbstverständnis des Programmierers als Autor. Als solcher befasst sich dieser vorwie- gend mit der inhaltlichen Darstellung und dem verwendeten Stil. Es kommt darauf an, dass die Systembeschreibung verständlich ist. KNUTH behauptet, dass die daraus entstehenden Programme automatisch verständlicher und leichter benutzbar werden und die Dokumentation genau mit den Programmen übereinstimmt.

Im Bereich Onlinehilfe unterscheiden wir grundsätzlich zwischen statischer (kontextun- abhängiger) und dynamischer (kontextabhängiger) Hilfe. Die dynamische, kontextab- hängige Hilfe ist abhängig von der jeweiligen Situation des Anwenders. Die Hilfe kann dem Anwender als Dialoghilfe, Direkthilfe oder eingebettete Hilfe erscheinen

Das Kriterium der Gliederung der Hilfevarianten der kontextabhängigen Onlinehilfe ist die Nähe zur Software. Die Dialoghilfe erläutert z.B. das gerade aktive Fenster als Gan- zes, die Direkthilfe gibt Informationen zu Feldern, Buttons oder Menüpunkten oder anderen GUI-Elementen und die eingebettete Hilfe ist direkt in die Softwareoberfläche integriert und stets sichtbar

Grundsätzlich ist HTML Help ein Microsoft-Format, also ein propietäres Format, wel- ches auf die Betriebssysteme von Microsoft ausgerichtet ist. Das Format dient haupt- sächlich der Erstellung von Onlinehilfen für Anwendungssoftware, Schulungsunter- lagen und Intranet- oder Internet-Websites. Die HTML-Hilfe besteht aus einer einzigen kompilierten und komprimierten Datei.
Im Unterschied zur HTML-Hilfe von Microsoft weisen die browserbasierten Hilfe- formate eine ganze Struktur von Pfaden, Unterpfaden und Dateien auf. Sie verwenden Web-Technologien und sind deshalb plattformunabhängig und damit für Windows, Unix, Linux und Macintosh verwendbar.

Bei der serverbasierten Hilfe liegt die zentrale Verwaltung der Hilfedateien auf einem Server, der stets aktuelle Hilfetexte zu Verfügung stellt. Viele Browser können auf den zentralen Server zugreifen.
Manche Produkte können zusätzliche Informationen über automatisierte Feedback- und Reporting-Technologien gewinnen. Hierdurch werden immer besser „passende“ Hilfen möglich, da das Hilfesystem das Nutzerverhalten analysiert und lernt.

Bei der Zielgruppenanalyse müssen folgende Fragen geklärt werden: – Wie setzt sich der Benutzerkreis zusammen? Handelt es sich um Anfänger, Fortge- schrittene, Spezialisten, eine bestimmte Berufsgruppe?
– Welche Voraussetzungen bringen die Benutzer der Software und der Dokumentation mit?
– Welche Interessen haben die Benutzergruppen? Welche Anforderungen an das Lay- out, die Gliederung, die ausgewählten Beispiele ergeben sich daraus?
– Welcher Detaillierungsgrad, Umfang und Schreibstil der Dokumentation passt auf die Nutzergruppe?
Die Analyse der „User“ ist notwendig, damit die Software nicht zum Selbstzweck wird. Die Anwender benutzen Software als Mittel zum Zweck und nicht etwa, um die Menü- struktur oder Befehlsleisten zu bewundern. Computerspiele werden nicht gespielt, um die 3D-Grafiken zu feiern, sondern weil sie Spaß machen. Gute Softwaredokumentation hat die Aufgabe, die Nutzer bei dem, was sie mit dem Programm tun möchten, zu unter- stützen.

Ordnende Strukturen sind für umfangreiche Handbücher besonders wichtig. Untersu- chungen im Bereich der Lesbarkeitsforschung belegen, dass die Gliederung und Struk- tur maßgeblich für die Lesbarkeit des Textes sind. Sinn der Kontextebenen ist es, die ausführliche Beschreibung mit einer komprimierten und übersichtlichen Darstellung zu verbinden. Kontextebenen sollen dem Leser das schnelle und gezielte Auffinden der gewünschten Information vereinfachen.

Wir unterscheiden drei Kontextebenen: Kontextebene (1) und (2) betreffen den Seiten- aufbau und Kontextebene (3) die Redaktionsbereiche. Auf der Kontextebene (1) sind die Marginalien zu finden, zur Kontextebene (2) gehören Kopfzeile, Fußzeile, Kapitel- überschrift, Modulname oder Seitennummer und der Kontextebene (3) sind Registratu- ren, Trennblätter, Markierungen, Bindung usw. zuzuordnen.

Bei der ingenieursmäßigen Herangehensweise geht es um die zentrale Frage, wie die Abläufe und Arbeitsschritte optimal gesteuert werden können, um die nachträgliche Bearbeitung und aufwendige Fehlerbehebung weitgehend auszuschalten. Die Zielgrup- penanforderungen sind im Vorfeld analysiert und während des Entwicklungsprozesses getestet worden, Qualitätsziele werden zu Beginn festgelegt, der Umfang und die Art der Dokumentation sind sorgfältig geplant, Risikofaktoren werden zu Beginn des Doku- mentationsprozesses und bei jedem Meilenstein im Projekt beurteilt. Bei dieser Sicht- weise können Korrekturen – falls erforderlich – schnell durchgeführt werden. Wichtig ist auch, dass die erforderlichen Ressourcen für das Dokumentationsprojekt von Beginn an ausreichend eingeplant wurden, damit die zeitgerechte Erstellung der Dokumentati- onsunterlagen sichergestellt ist.

BALZERT definiert Softwareengineering als zielorientierte Bereitstellung und systemati- sche Verwendung von Prinzipien, Methoden, Konzepten, Notationen und Werkzeugen für die arbeitsteilige, ingenieurmäßige Entwicklung und Anwendung von umfangrei- chen Softwaresystemen

Im Wasserfallmodell wird der gesamte Entwicklungsprozess in mehrere, in sich abge- schlossene Phasen aufgeteilt. Diese Phasen werden sequenziell durchlaufen. Mit einer neuen Phase kann erst begonnen werden, wenn die vorhergehende abgeschlossen ist.

Im praktischen Einsatz haben sich folgende Schwächen des Wasserfallmodells heraus- gestellt:
– Das Modell basiert auf der unrealistischen Annahme, dass sich die Anforderungen im Verlauf des Projektes nicht verändern, sondern dass in jeder Phase die zu bearbeiten- den Aufgaben und Problemstellungen vollständig erkannt und verstanden wurden. Der Projektverlauf ist aber nicht immer genau planbar.
– Der Kunde/Benutzer bekommt erst das fertige System zu sehen. Damit können even- tuelle Korrekturen erst spät berücksichtigt werden und das Projekt verzögert sich.

Dokumentation nimmt im Wasserfallmodell einen wichtigen Stellenwert ein. Innerhalb der einzelnen Phasen werden hierarchisch strukturierte Aktivitäten nach Checklis- ten abgearbeitet. Zu jeder Aktivität gehört ein Ergebnisdokument

Die wichtigsten Dokumente sind Lastenheft und Pflichtenheft. Das Lastenheft gehört dem Auftraggeber und das Pflichtenheft verbleibt beim Auftragnehmer. Im Lastenheft werden die vom Auftraggeber festgelegten Anforderungen an die Lieferungen und Leis- tungen eines Auftragnehmers innerhalb eines Auftrages festgehalten. Die Inhalte des Lastenheftes sind präzisiert, vollständig und nachvollziehbar und mit technischen Fest- legungen der Betriebs- und Wartungsumgebung verknüpft. Im Pflichtenheft erarbeitet der Auftragnehmer die Umsetzung der vom Auftraggeber vorgegebenen Anforderungen des Lastenheftes.

Die Anpassung der standardisierten Module des V-Modells auf ein konkretes Projekt erfolgt durch das sogenannte Tailoring. Die Anwendung bzw. Anpassung erfolgt über Projektmerkmale oder Projekttypen. Die Anpassung nach Projektmerkmalen erfolgt in vier Stufen:

1. Die spezifischen Projektmerkmale werden herausgearbeitet, die in einem konkreten Projekt vorhanden sind.
2. Diese Merkmale werden einem bestimmten Projekttyp zugeordnet. Damit sind auch die Projektdurchführungsstrategien und Entscheidungspunkte für die Fertigstellung bestimmter Produkte (Ergebnisse) eingegrenzt.
3. Vom V-Modell werden die obligatorischen und fakultativen Vorgehensbausteine vorgegeben. Im Projekt kann bestimmt werden, welche Bausteine aufgenommen und welche gestrichen werden sollen.
4. Resultat ist eine auf das konkrete Projekt angepasste Projektplanung und -steuerung

Beim Tailoring nach Projekttypen wird die erste Stufe (herausfiltern spezifischer Pro- jektmerkmale) ausgelassen und die Vorgehensweise für das Projekt wird gleich aus den Projekttypen abgeleitet.
Für folgende Projekttypen existieren im V-Modell konkrete Vorgehensbausteine mit Projektdurchführungsstrategien und Entscheidungspunkten: Systementwicklungspro- jekt eines Auftraggebers, Systementwicklungsprojekt eines Auftragnehmers und Ein- führung und Pflege eines organisationsspezifischen Vorgehensmodells.

Die agile Softwareentwicklung basiert auf der Annahme, dass Projekte in der Realität oft nicht linear planbar, sondern einem ständigen Wandel unterlegen sind. Beispiele für solche Planabweichungen sind:

– Änderung im Projektteam,
– Änderung im technologischen Umfeld,
– Änderung der Kundenanforderungen,
– Änderung durch Konkurrenz,
– Änderung im Markt in der Wettbewerbssituation.

Scrum gilt als dokumentationsarmer Softwareentwicklungsprozess. Bei Scrum steht die Entwicklung von Software an oberster Stelle. Der Kunde (Product Owner) ist in den Entwicklungsprozess von Anfang an mit eingebunden. Er schreibt die Anforderungsspezifikation selbst, indem er in „seiner Sprache“, unabhängig von technischen Details, die sogenannten User Stories verfasst, die die Grundlage für die Umsetzung in Programmcode bilden. Diese User Stories dokumentiert er auf Story Cards. Die Story Card enthält die folgen- den Inhalte:
---> Auf der Vorderseite steht: – Als <Rolle> will ich <Funktionalität> [, sodass < Ziel>] – Nutzen-Schätzung – Kosten-Schätzung
---> Auf der Rückseite stehen die Akzeptanzkriterien für die Testfälle in der Form: – Unter Voraussetzung dass <Vorbedingung> wenn <Trigger> dann <Ergebnis>

User Stories unterscheiden sich von traditionellen Anforderungsspezifikationen durch den Detaillierungsgrad. User Stories sollen gerade genug Informationen beinhalten, um eine grobe Schätzung über den Implementierungsaufwand abgeben zu können und als Grundlage für die Akzeptanztests zu dienen. Die Umsetzung der User Story findet zwi- schen Entwicklern und dem Kunden statt, welche die User Stories zu diesem Zweck auf eine detailliertere Beschreibung in Form von Tasks (Aufgaben) herunterbrechen. Die Tasks (Aufgaben) werden auf Task Cards dokumentiert, die in jeweils ein bis drei Tagen bearbeitet werden können

m Verlauf eines Scrum-Projektes werden verschiedene Dokumentationsartefakte erstellt. Dazu gehören die Story Cards (User Stories), die Task Cards, das Product Backlog, das Sprint Backlog, das Burndown Chart und das Impediment Backlog. Anhand der Story Cards werden die Ziele, die in einem Sprint erreicht werden sollen, mit dem Kunden und den Entwicklern gemeinsam diskutiert. Die Task Cards enthalten technische und organisatorische Aufgaben, die für die Realisierung des Systems erfor- derlich sind. Die Task Cards sind wie die Story Cards als konkrete Arbeitsaufträge für die Entwickler zu verstehen. Das Product Backlog umfasst alle für das Projekt aktuell geplanten User Stories und Aufgaben, das Sprint Backlog nur die für den nächsten Sprint geplanten. Das Burndown Chart verfolgt den Projektfortschritt anhand der noch zu erledigenden Aufgaben und das Impediment Backlog listet alle noch zu beseitigen- den Schwierigkeiten des Projektes.
In Scrum sollten keine unnötigen Dokumente erzeugt werden. Der Bedarf entscheidet über die Dokumentationsartefakte.

RUP ist ein standardisierter Softwareengineeringprozess, der den gesamten Entwicklungszyklus abdeckt und große Projekte überschaubar und planungssicher macht. RUP baut auf Anwendungsfällen auf, die in einer webbasierten, durchsuchbaren Wissensbasis abgebildet sind. Entwicklerteams haben so Zugriff auf die sogenannten „Best Practices“, Entscheidungshilfen, Werkzeuge und Vorlagen für alle kritischen Stellen des Entwicklungszyklus.

Die Systemdokumentation in RUP besteht aus Artefakten, die sich aus Text und Dia- grammen zusammensetzen. In RUP werden über 100 Artefakte beschrieben, davon ist ca. die Hälfte als Dokument klassifiziert. Durch das iterative Vorgehen entsteht im Idealfall eine konsistente Systemdokumentation

Für die Kernaufgabe „Implementierung“ besteht das Artefakt aus einem Implementierungsmodell und einer Architekturbeschreibung.

Eine gute Qualität von Softwaredokumentation entsteht nicht einfach als „Nebenpro- dukt“, sondern kann nur durch sorgfältige Planung und Verankerung als Management- aufgabe sichergestellt werden. Es fängt bei der Entscheidung darüber an, was die Quali- tät technischer Dokumentationen eigentlich ausmacht, denn diese hängt von dem Blickwinkel ab: – Schnelle Produktentwicklung ist Qualität. – Niedrige Kosten bedeuten Qualität. – Eine vollständige technische Beschreibung ist Qualität. – Eine fehlerfreie Beschreibung ist Qualität. – Eine ansprechende Publikation ist Qualität.

Für das Management sind folgende Fragenkomplexe zu bewältigen: Welche Qualitäts- merkmale sollen angelegt werden? Wie können diese umgesetzt werden? Wie können die Ergebnisse kontrolliert werden? Diese Fragenbereiche entsprechen den klassischen Managementaufgaben: – Die Planung, Steuerung und Kontrolle von Prozessen. – Festlegung von Projektzielen und Meilensteinen. – Schätzung des Zeit- und Ressourcenaufwands. – Projektfortschreibung.– Aufwandsschätzung bei auftretenden Änderungen.

Vor diesem Hintergrund ist die Qualität von Softwaredokumentation ebenso wie das Entwicklungsprojekt selbst zu handhaben. Nur so lassen sich die Abläufe verbessern und damit auch die Qualität!

Für die Softwaredokumentation sind folgende rechtliche Bereiche von Bedeutung: – Handelsrecht, Vertragsrecht und vertragliche Anforderungen an die Dokumentation, – Bundesdatenschutzgesetz (BDSG), – Grundsätze ordnungsgemäßer Speicherbuchführung (GoS) und Grundsätze ord- nungsgemäßer Datenverarbeitung (GoDV),
– Produkthaftungsgesetz, – bei bestimmten Programmen, z.B. Personalabrechnung, sind mehrere Gesetze anwendbar.

Beipielhaft lassen sich folgende Qualitätsmerkmale anführen: – Korrektheit, – Vollständigkeit, – Verständlichkeit und Lesbarkeit, – Konsistenz, – Aktualität, – Phasenbezug, – Redundanzfreiheit.

Eine unmittelbare Anwendung der Qualitätsmerkmale auf die Softwaredokumentation ist nicht möglich. Es gibt keinen einheitlichen Standard für die Qualitätsmerkmale und -kontrolle für Softwaredokumentation. Die Qualitätsmerkmale bilden die Grundlage für die Auseinandersetzung des Projektmanagements mit der Qualitätssicherung für Dokumentationen. Ziel ist die Entwicklung unternehmensspezifischer Qualitätssicherungssysteme für den Bereich der Dokumentation.

Texte sind oft schwer lesbar und unverständlich. Warum ist das so? Die Verständlich- keitsforschung untersucht diesen Bereich gründlich und will geeignete Mittel und Methoden bereitstellen, mit denen die Textverständlichkeit verbessert werden kann.

Die Verständlichkeitsforschung lässt sich in folgende Bereiche einteilen: – Untersuchungen zur Verständlichkeit schriftlicher Texte (Readability). Hiermit sind Untersuchungen gemeint, die der Frage nachgehen, welche linguistischen und ande- ren Faktoren (z.B. Typografie, Bildunterstützung) die Verständlichkeit eines Textes verbessern oder in Mitleidenschaft ziehen.
– Psychologische Verständlichkeitsforschung (z.B. sogenanntes Hamburger Verständ- lichkeitskonzept). Die Untersuchungen bewerten globale Konzepte wie Einfachheit, Kürze, Gliederung und anregende Zusätze.
– Linguistische Verständlichkeitsforschung: Bezug auf spezifisch linguistische Fakto- ren, z.B. Lexikon (Terminologie), Syntax, Diskursstruktur, Typen von Sprechhand- lungen usw.

Lesbarkeit und Verständlichkeit von Texten allgemein können mittels folgender Metho- den berechnet bzw. beurteilt werden: – Cloze-Procedure-Test, – Flesch-Reading-Ease-Index, – Gunning-Fog-Index, – Flesch-Kincaid-Index, – Readability Formula von DICKES/STEIWER, – New-Reading-Ease-Index von FARR/JENKINS/PATTERSON, – Automated-Readability-Index (ARI) von SENTER/SMITH, – Readability Formula von DANIELSON/BRYAN, – SMOG-Index von MCLAUGHLIN, – Hamburger Verständlichkeitskonzept von LANGER, – Textverständlichkeit nach GROEBEN, – Checklisten-Verfahren nach BOEDICKER, – Tekom-Richtlinie.

Lesbarkeitsformeln werten linguistische und stilistische Texteigenschaften aus, die die „Oberflächenstruktur“ von Texten betreffen. Sie sagen absolut nichts über die Güte des Textinhaltes aus. Manche Experten bezweifeln daher, ob die Werte der Lesbarkeitsfor- meln überhaupt zu validen Aussagen bezüglich Lesbarkeit führen. Als Kritikpunkte für den Einsatz der Formeln werden genannt: – keine Berücksichtigung von zielgruppenspezifischen Faktoren wie Intelligenz, Moti- vation, Fähigkeiten, Erwartungen,
– keine Berücksichtigung von Inhalt, Organisation, Textaufbereitung, Format, Umfang, Dichte, Erklärungen etc.,
– keine Berücksichtigung der Wechselwirkungen zwischen Syntax und Semantik, – keine aufgabenbezogene Evaluierung, sondern lediglich personenbezogen.
Die Anwendung der Formeln führt zu Aussagen über die Dokumentationsqualität in Unternehmen, die Dokumentationen vorwiegend selbst erstellen, und unterstützt somit den Prozess der internen Qualitätssicherung.

Usermanuals und Onlinehilfen werden von einem technischen Redakteur erstellt und betreut. API-Manuals und Testcases werden von Softwareentwicklern erstellt und betreut. Spezifikationsmanuals und Vertragsdokumente werden vom Projektmanager betreut. Bei der Erstellung können sowohl der Kunde wie auch Softwareentwickler und Manager mitwirken