at

LV-Treffen: Softwaredokumentation im agilen Umfeld – kann das überhaupt funktionieren? (02.12.2016)

Franz Steiner, tekom Österreich

41 Teilnehmerinnen und Teilnehmer (25 Mitglieder und 16 Interessenten) kamen am 02. Dezember 2016 an die Fachhochschule Joanneum (Graz) und fanden heraus, dass Softwaredokumentation im agilen Umfeld kein Widerspruch in sich, sondern mit einigem Veränderungswillen absolut zu meistern ist.

Doch zunächst stellten FH-Prof. Mag. Dr. Heinz M. Fischer, FH-Prof. DI Dr. Konrad Baumann und DI Werner Schwaiger die FH Joanneum und den neuen berufsbegleitenden Master-Lehrgang "Technische Dokumentation" vor, der 3 Semester dauert und im Sommersemester 2017 startet.

"Gebt mir ein lauffähiges Build, die User Stories und Zugriff auf die Testdatenbank und die Basis für meine Arbeit als Technischer Redakteur ist gelegt."

So brachte der erste Referent Michael Valent (AIM Software) die Voraussetzungen für eine erfolgreiche Arbeit als Technischer Redakteur in einem agilen Umfeld auf den Punkt.

Was ist Softwaredokumentation überhaupt?

Zu Beginn legte Michael Valent in seinem Vortrag dar, was alles unter dem Begriff Softwaredokumentation verstanden wird. Dazu gehören nicht nur GUI-Texte, Tooltips, Fehlermeldungen, Kommentare im Code, Schnittstellendokumente etc., die typischerweise von Entwicklern geschrieben werden, sondern auch Handbücher, Onlinehilfen, Begleitdokumente (z. B. Release Notes) sowie Schulungsunterlagen, für deren Erstellung meistens Technische Redakteure zuständig sind. Fallweise, so der Referent, übernehmen Technische Redakteure außerdem die Qualitätssicherung der Entwicklertexte. Was genau zur Softwaredokumentation eines Unternehmens gehört, ist abhängig von der Art der Software (z. B. Apps, Standardtools, Profitools, Plattformen) und den Zielgruppen (Produktbenutzer, Produktadministratoren, Systemadministratoren, Produktentwickler etc.).

"Klassische" vs. agile Entwicklungsmethoden

Im Anschluss erklärte Michael Valent die Unterschiede zwischen „klassischen“ Entwicklungsmethoden (Stichwort Wasserfallmodell oder V-Modell) und agiler Projektabwicklung (stellvertretend seien hier die Methoden Lean Development, Kanban und Scrum genannt). Während die klassischen Entwicklungsprojekte plangetrieben abgewickelt werden, d. h. Anforderungen sind fix, Ressourcen und Termin jedoch variabel (bzw. geschätzt), sind agile Entwicklungsprojekte wertgetrieben, d. h. Ressourcen und Termin sind fix, die Anforderungen aber variabel (bzw. geschätzt). Sehr anschaulich vermittelte der Referent den Teilnehmern dabei die fürs Verständnis notwendige Terminologie.

Als Top-Tipps aus seiner langjährigen Erfahrung in agilen Entwicklungsteams gab Herr Valent den Zuhörern Folgendes mit auf den Weg:

  • Die Technische Redaktion muss bereits zu Beginn des Projekts integraler Teil des Teams sein und es über sämtliche Sprints, Iterationen und Release-Zyklen bleiben.
  • Umfang, Ziel und Form(en) der geforderten Dokumentation müssen klar und verbindlich zu Beginn des Projekts vereinbart werden.
  • Softwaredokumentation in agilen Entwicklungsteams ist nur mit strukturiertem, modularen Aufbau möglich. Daher, so der Referent, seien professionelle Tools wie z. B. FrameMaker, MadCap, AuthorIT, SCHEMA und Confluence ein absolutes Muss, Microsoft Word hingegen ein eher ungeeignetes Werkzeug.

Doch was kann die Technische Redaktion tun, damit sie diese Integration ins agile Team erreicht? Auch auf diese Frage lieferte Michael Valent Antworten:

  • Kommunizieren, kommunizieren, kommunizieren: Ja, es mag sich nach einer Binsenweisheit anhören, aber gerade in einer so dynamischen Entwicklungsumgebung ist die Kommunikation das A und O.
  • Selbstbewusst auftreten: Der Technische Redakteur verfügt über ein großes Wissen und ist ein wichtiger Stakeholder im Entwicklungsteam – das darf man ruhig merken.
  • Einfühlungsvermögen zeigen: Auch die anderen Mitglieder des Entwicklungsteams sind Experten auf ihrem Gebiet und verdienen, dass ihnen derselbe Respekt und dasselbe Verständnis entgegengebracht wird, wie man es sich für sich selbst wünscht.
  • Verlässlich sein: Vereinbarungen müssen eingehalten, Probleme rechtzeitig kommuniziert werden; nur, wenn sich alle Teammitglieder und alle Teams aufeinander verlassen können, kann ein agiles Entwicklungsprojekt funktionieren.

Normen wichtig, aber keine Gesetze

Dass es zum Thema Softwaredokumentation mehr Normen gibt, als man vielleicht gemeinhin annimmt, zeigte anschließend Ing. Martin Rieder (CAVEO). Er wies darauf hin, dass Normen zunächst als eine Sammlung von "Best Practices" betrachtet werden können und als Orientierungshilfe, Grundlage für Qualitätssicherung, Zertifizierungen und Akkreditierungen sowie als Basis für ein gemeinsames Verständnis und Verträge verwendet werden können. Normen haben zwar einen gewissen Rechtscharakter, sind jedoch keine Gesetze und ihre Anwendung erfolgt auf freiwilliger Basis.

Da die EN 82079-1 Erstellen von Gebrauchsanleitungen nach Meinung des Referenten nicht optimal auf Softwaredokumentation anwendbar ist, stellte er die relevanten Normen der ISO-Reihe 2651x vor (Opens internal link in current windows. Liste am Ende des Berichts). Als Empfehlungen für die Praxis gab Herr Rieder den Teilnehmern mit, sich nicht von Normen verrückt machen zu lassen, sondern immer abzuklären, welche Normen überhaupt relevant sein könnten, Ziel und Zweck dieser Normen zu erkennen und zu verstehen, sie zu interpretieren und für den eigenen Bereich anzuwenden. Dabei sei es wichtig, auch ab und zu über den Tellerrand hinauszuschauen und ggf. Kontakt zu Normengremien zu halten, um sich seine Arbeit und die Zusammenarbeit mit anderen leichter zu gestalten.

Einführung agiler Methoden – ein Praxisbericht

Nach der Mittagspause stellte Markus Nestler (BMW / München) via Skype "BA.MOBILE - Ein agiles Projekt" vor. Dabei ging es um fahrzeugspezifische Betriebsanleitungen im Fahrzeug als Apps, die auch offline verfügbar sind (Beispiel: BMW Driver's Guide). Die wesentlichen Anforderungen und Features dieses Projekts waren:

  • intelligente Suchfunktion
  • Lesezeichen
  • Videoinhalte
  • Schritt-für-Schritt-Anleitungen
  • Aufruf spezifischer Information mittels Smartphone-Kamera
  • gute Feedbackmöglichkeit für die Nutzer der Betriebsanleitungen

Zur Umsetzung dieser Anforderungen wurde ein BMW-spezifisches Vorgehensmodell entwickelt, wodurch die Fortschritte immer sichtbar waren und die Projektteilnehmer trotz Flexibilität und Handlungsspielraum bei der Umsetzung immer ein Gefühl für das fertige Produkt behielten. Außerdem nannte der Referent das direkte und zeitnahe Feedback als zentralen Vorteil des Vorgehens. Doch Herr Nestler verschwieg auch die Herausforderungen und Stolpersteine des Projekts nicht; so war "agile Entwicklung" zu Projektbeginn (2012) noch kein vertrautes Thema, externe Unterstützung und Training noch schwierig zu bekommen. Entsprechend mussten sämtliche Prozesse, Tools und Templates für agiles Vorgehen angepasst bzw. überhaupt erst aufgebaut werden. Die hohe Kapazitätsbindung aller bereits während der Entwicklung war darüber hinaus ein Effekt, der so nicht vorhergesehen wurde und auf den das Projektteam reagieren musste.

Die Herausforderungen wurden gemeistert, das Vorgehen hat sich bewährt und heute gehört agiles Entwickeln zum Standard. Es gibt agile Projekte mit global verteilten Teams, Templates und Tools (JIRA und Confluence von Atlassian) sind vorhanden, es gibt interne Trainings und Diskussionsrunden / Erfahrungsberichte und ein Modell für die Zusammenarbeit mit externen Partnern. Bewährt hat sich der Einsatz von „agilen Coaches“, die die Teams unterstützen.

Frag' doch die Experten!

Vom geballten Wissen von 4 Experten konnten die Zuhörer bei der darauffolgenden Podiumsdiskussion profitieren: Mag. Petra Herbst (INFONOVA GmbH), Mag. Maria Lanthaler (TU Graz – CAMPUSonline), Caterina Richter, MA (TU Graz – CAMPUSonline) und Michael Valent (AIM Software) stellten zunächst sich selbst, ihre Unternehmen und ihr agiles Umfeld vor und gingen dann auf Fragen des Auditoriums ein. Diskutiert wurden unter anderem folgende Fragen:

  • Wie wird die Herausforderung "Lokalisierung" gehandhabt?
  • Gibt es im agilen Umfeld Änderungen in der Art von Beschreibungen?
  • Unterschiede Benutzerdokumentation - API-Dokumentation?
  • Wie sieht der Informationsfluss aus und was sind die Auswirkungen auf die Qualität?
  • Wie handhabt man "konzeptionelle" Dokumentation im agilen Umfeld?
  • Was mache ich, wenn ich als Technischer Redakteur mehr als 2 agile Entwicklungsteams betreuen muss?
  • Wie gehe ich mit "veralteten" Sprints um?
  • Sind agile Arbeitsweisen auch im Bereich Geräte- bzw. Hardwareentwicklung denkbar?
  • Welche Tools kommen zur Anwendung?
  • Hat agiles Vorgehen auch Nachteile?

Zum Abschluss der Veranstaltung ging die Mehrzahl der Teilnehmer noch gemeinsam zum nächstgelegenen Adventmarkt und ließ den Tag bei Glühwein Revue passieren und ausklingen.

Relevante Normen für die Softwaredokumentation

  • ISO 26511: Requirements for managers of user documentation
  • ISO 26512: Requirements for acquirers and suppliers of user documentation
  • ISO 26513: Requirements for testers and reviewers of user documentation
  • ISO 26514: Requirements for designers and developers of user documentation
  • ISO 26515: Developing information for users in an agile environment

Vortragsunterlagen

Die Unterlagen stehen tekom-Mitgliedern im Bereich Downloads zur Verfügung.
Opens internal link in current windowZum Download... (nur für Mitglieder)

Info-Corner
Registrierung 1
Registrierung 2
Begrüßung durch Dr. Fischer, Dr. Baumann und DI Schwaiger (FH Joanneum)
Werner Schwaiger stellt den neuen FH-Lehrgang "Techn. Dokumentation" vor
Michael Valent erklärt die Scrum-Terminologie
Einleitung zum BMW-Vortrag durch Werner Schwaiger
Diskussion mit Markus Nestler / BMW München via Skype
Podiumsdiskussion: C. Richter, M. Lanthaler, P. Herbst, M. Valent
Ausklang auf dem Adventmarkt