Embed Size (px)
Citation preview
Andrea Gocke [email protected]
Mareike von der Stück [email protected]
NORM 13
Software… was gibt's denn da zu
dokumentieren?
Stuttgart, 12. November 2014
Agenda
15' Einstieg
20' Theorie
Von welchen Faktoren wird Software-Dokumentation beeinflusst?
45' Praxis
Zielgruppen beschreiben und Texte zielgruppengerecht optimieren
10' Abschluss
2 © 2
014 G
ocke, von d
er
Stü
ck
Einstieg
3 © 2
014 G
ocke, von d
er
Stü
ck
Was stellen Sie sich unter Software und Software-Doku vor?
Mit welchen Aspekten von Software beschäftigen Sie sich?
Einflussfaktoren auf Software-Doku
5 © 2
014 G
ocke, von d
er
Stü
ck
Software-Dokumentation
Einflussfaktoren auf Software-Dokumentation
6 © 2
014 G
ocke, von d
er
Stü
ck
Normen • Gesetze
• Verordnungen
• Richtlinien
• Vorschriften
• Verträge
• Leistungs-
beschreibungen
Unternehmen • Strategische Ziele
• Corporate Identity
• Redaktionsprozess,
Informationsbeschaffung
• Entwicklungsbedingungen, Logistik,
...
Zielgruppen • Märkte, Branchen
• Sprachen
• Vorwissen
• Datensicherheits-
bewusstsein
• Arbeitsumfeld
• Strategien
• Motivation
Software (als / im Produkt) • Struktur und Software-Umgebung
• Zweck, Funktionen, Arbeitsweisen
• Gefährdungspotenzial
• Pflege und Wartungserfordernis
Adaptiert, Quelle: Schäflein-Armbruster, Schmeling;
Planen, Strukturieren, Standardisieren
Bei Software im Produkt
• Produktsicherheits-
gesetz
• Produkthaftungs-recht
• Produktsicherheits-
normen
• Vertragsrecht
Arten von Software
• Nähe zum Anwender
• Software als versus im Produkt
• Standardisierungsgrad
• Komplexität
• Branche (Personalwesen, Medizin, …)
generische Zielgruppen:
• Endbenutzer
• Superuser
• Entscheider
• Administratoren
• IT-Abteilung
• Implementierungsteam /
Berater
• Hosting
• Entwickler
• …
• Content Management System
• Entwicklungsumgebung
• Code
• Oberfläche
• Text Repositories
Einflussfaktoren Software und Unternehmen
Planung Entwicklung
(Software, Oberfläche incl. Texte, Doku, Übersetzung, Test)
Test und Validierung
Produktion Auslieferung
Entwicklungsteam: Entwickler, Informations-
entwickler, Übersetzer, Usability-Experte, Tester,
Qualitätsexperte
Software-Entwicklung (agil oder Wasserfall)
7 © 2
014 G
ocke, von d
er
Stü
ck
Phase
Übergabe
Phase
Agile Entwicklung ISO IEC 26515
Wasserfall ISO 26514 (ISO IEC 12207 und ISO 15288)
Einflussfaktor Normen
Inhaltliche Aspekte
• Branchenspezifische Normen, z. B. aus dem Bereich Medizinprodukte, Buchhaltung, Luftfahrt
Redaktionelle Tätigkeiten
• ISO IEC 26514: Anforderungen an Designer und Entwickler von Benutzerdokumentationen
• DIN EN 82079-1: Erstellen von Gebrauchsanleitungen
Wahl und Gestaltung Software-Oberfläche
• ISO 9241: Ergonomische Anforderungen für Bürotätigkeiten mit Bildschirmgeräten
• DIN EN ISO 14915: Software-Ergonomie für Multimedia-Benutzungsschnittstellen
Prozessmodelle
• ISO IEC 26515: Entwicklung von Benutzerdokumentation in einem agilen Umfeld
• ISO IEC 26514: Wasserfallmodell
8 © 2
014 G
ocke, von d
er
Stü
ck
Einflussfaktor Normen
ISO IEC IEEE 26511:2011-12
System-und Software-Engineering - Anforderungen für Manager von
Benutzerdokumentation
ISO IEC IEEE 26512:2011-06
System-und Software-Engineering - Anforderungen für Ankäufer und Lieferanten der
Benutzerdokumentation
ISO IEC IEEE 26513:2009-10
System und Software-Engineering - Anforderungen an Prüfer und Gutachter von
Benutzeranleitungen
ISO IEC IEEE 26514:2008-06
Informationstechnik - Software und System-Engineering - Anforderungen an
Designer und Entwickler von Benutzerdokumentationen
ISO IEC IEEE 26515:2011-12
System-und Software-Engineering - Entwicklung von Benutzerdokumentation in
einem agilen Umfeld
Normenreihe ISO IEC IEEE 26511-26515
9 © 2
014 G
ocke, von d
er
Stü
ck
Einflussfaktor Zielgruppe
Fallstrick Ergebnis
Die eigene Lernkurve teilen. Sie schreiben das auf, was Sie gerade gelernt haben,
statt die Fragen der Zielgruppe zu beantworten
Offensichtliche
Informationen beschreiben.
Sie beurteilen das Wissen der Zielgruppe falsch und
stellen Informationen bereit, die bereits bekannt oder
trivial sind.
Nicht relevante Inhalte
bereitstellen.
Sie kennen die Zielgruppe nicht und beschreiben Dinge,
die die Zielgruppe nicht betreffen.
Kontext weglassen. Sie stellen relevante Information bereit, stellen aber
keinen Bezug zur Anwendungs-/Arbeitssituation her.
Informationen vermischen,
die für unterschiedliche
Zielgruppen relevant sind.
Sie schreiben aus Ihrer Sicht, nicht aus der Sicht der
Zielgruppe. Sie schreiben alles ungefiltert und unsortiert
auf: Technik, Betriebswirtschaft, Kontext, Detailtiefe,
Oberfläche usw. werden gemischt.
Was passiert, wenn Sie die Zielgruppe nicht berücksichtigen
10 © 2
014 G
ocke, von d
er
Stü
ck
Einflussfaktor Zielgruppe
Persona-Methode
Alan Cooper (Software-Entwickler)
Entwicklung von Software anhand prototypischer Benutzer mit „Gesicht“
Setzt eine Zielgruppenanalyse voraus
Wer-macht-was-Matrix
Edmont Weiss: Topic-User-Matrix
Übersicht über alle Aufgaben und deren typische Zielgruppen
Ziel: Informationen in Informationsprodukten so zusammenstellen, dass jede
Zielgruppe die benötigten Informationen erhält
Zielgruppen identifizieren und beschreiben
11 © 2
014 G
ocke, von d
er
Stü
ck
Einflussfaktor Zielgruppe
Wie werden Personas erstellt?
Extraktion von Informationen aus Zielgruppeninterviews
Zusammengefasst auf 1 bis 2 Seiten
Ergänzt um wenige erfundene persönliche Details, um einen realistischen Charakter
zu erzeugen
Was ist der Vorteil von Personas?
Abstrakte Informationen über Zielgruppen erhalten ein Gesicht
Unterstützung bei Brainstormings, Use-Case-Spezifikationen, Feature-Definitionen
Erleichterung der Kommunikation zwischen Engineering und Entwicklung
Persona-Methode
12 © 2
014 G
ocke, von d
er
Stü
ck
Einflussfaktor Zielgruppe
Wie wird eine Wer-macht-was-Matrix erstellt?
In einer Tabelle werden zeilenweise die Aufgaben aufgelistet
In Spalten werden Zielgruppen zugeordnet
Was ist der Vorteil einer Wer-macht-was-Matrix?
Übersicht über alle Aufgaben, die mit der Software erledigt werden
Sortierung der Aufgaben nach Use-Cases möglich
Identifikation der wahrscheinlichen Zielgruppenfragen
Wer-macht-was-Matrix
13 © 2
014 G
ocke, von d
er
Stü
ck
Informationsangebot zielgruppengerecht bestimmen
1. Welche Zielgruppe(n) führen diese
Tätigkeit aus? *
2. Welche Eigenschaften der
Anwendungssituationen müssen
berücksichtigt werden?
3. Welche Fragen wird sich die
Zielgruppe stellen?
(Informationsbedarf)
4. Welche Inhalte müssen (fachlich
gesehen) der Zielgruppe vermittelt
werden?
5. Welche vorliegenden Informationen
sind nicht relevant?
6. Welche Informationseinheit(en)**
erfüllen den Informationsbedarf?
Bei mehreren voneinander getrennten
Informationseinheiten:
Welches ist die führende
Informationseinheit?
Welche Verweise werden benötigt?
14 (c)
2011, S
chm
elin
g +
Consultants
Gm
bH
*) Dies steht in der Wer-macht-was-Matrix **) Informationseinheit = Abschnitt oder Topic oder Text auf Oberfläche
Informationsarchitektur
15 © 2
014 G
ocke, von d
er
Stü
ck
Informationsarchitektur
Funktionsdesign Information
Mapping DITA
Topic-orientiertes Schreiben
Task-orientiertes Schreiben
Minimalismus
Strukturierungsmethoden nutzen (Industriestandards)
16 © 2
014 G
ocke, von d
er
Stü
ck
Informationsarchitektur
Primär
• Oberflächentexte (z.B. Feldbezeichner)
• Embedded Help (als Teil der Oberfläche, z.B. Mouseovers, Nachrichten oder erklärender Text)
Sekundär
• Kontextsensitive Hilfe (über Hilfebutton aufrufbar, erscheint in separatem Fenster)
• Separate Online-Dokumentation (z.B. Sicherheitsleitfaden)
• Papierdokumentation (z.B. ausgedruckter Sicherheitsleitfaden)
Informationskanäle nutzen
17 © 2
014 G
ocke, von d
er
Stü
ck
Software-Doku über alle relevanten und
erforderlichen Inhalte in geeigneter Form
an der geeigneten Stelle
Einflussfaktoren und Informationsarchitektur
18 © 2
014 G
ocke, von d
er
Stü
ck
Einfluss-faktoren
Informations-architektur Informationselemente,
Sequenzierung,
Formulierung/Gestaltung,
Informationskanal
Software, Unternehmen,
Normen, Zielgruppen
Übung Zielgruppen und Optimierung
19 © 2
014 G
ocke, von d
er
Stü
ck
Zielgruppen beschreiben
Beschreiben Sie eine (!) Zielgruppe der Abrechnungssoftware. Berücksichtigen Sie
dabei die Zielgruppeneigenschaften und typische Aufgaben im Zusammenhang mit
der Software.
Zielgruppeneigenschaften
Aufgaben und Ziele
Arbeitsumgebung
Rolle und Verantwortung
Informationszugriff
Allgemeine und fachliche Ausbildung
Fachliche Kompetenz
Produktspezifische Kompetenz
Bekannte und unbekannte Begriffe
Fremdsprachenkenntnisse
Verhalten
Übung (15')
20 © 2
014 G
ocke, von d
er
Stü
ck
Optimieren Sie
Wie würden Sie den Text
kürzen? Warum?
Komplexität der Software?
Zielgruppe der Software?
Welche Informationskanäle
halten Sie zur Übermittlung der
Information für sinnvoll?
Welche nicht? Warum?
Wo sehen Sie Klärungsbedarf
mit dem Software-Entwickler
und ggf. anderen Rollen im
Entwicklungsteam?
Übung (30')
21 © 2
014 G
ocke, von d
er
Stü
ck
Quelle: Installationsleitfaden oder Anwendungshilfe
Musterlösung
22 © 2
014 G
ocke, von d
er
Stü
ck
Vorher Nachher
Musterlösung: Schritt 1 – textimmanente Überarbeitung
23 © 2
014 G
ocke, von d
er
Stü
ck
Vorher: 401 Wörter Schritt 1: 123 Wörter (70 % weniger)
Annahmen
• Software = endlich komplex, lokale Installation
• Zielgruppe = Anwender/Endbenutzer
Maßnahmen
• Weg mit “stating the obvious”
und “Oberfläche abschreiben”
• Wo sind die Knackpunkte?
Was ist relevant?
relevant recyceln
neu
nicht relevant kürzen
Musterlösung: Sonstige Anmerkungen zum Originaltext
24 © 2
014 G
ocke, von d
er
Stü
ck
Vorher
Mehr “stating the obvious” geht nicht.
Ebenso Schritt 2 und 8.
Eher eine Meldung? Was ist “QC”? Wieso
lautet die Antwort nein? Dialogführung
anschauen und Text verbessern
Produktname ist nicht konsistent. Titel von
Dialogfenster, Meldungen etc. sind nicht
konsistent. Warum wird der Produktname
immer erwähnt? Ist eigentlich überflüssig,
sowohl in der Doku als auch auf der
Oberfläche.
Musterlösung: Schritt 2 – Anmerkungen zur Überarbeitung
25 © 2
014 G
ocke, von d
er
Stü
ck
Nach 1. Überarbeitung:
123 Wörter (70 % weniger)
Aber es geht noch mehr bzw. weniger!
Frage: Warum überhaupt
separate Installationsdokumentation?
Zielgruppenperspektive:
Information nah an den Benutzer bringen
• im Installationsdialog (Wizard)
• ggf. auch auf Webseite der Firma
Jetzt noch mal durchsieben!
Wirklich relevante Informationen?
Was ist der separaten Doku geschuldet?
Ergebnis:
• keine separate Installationsdoku nötig
• verbesserte Oberfläche und Dialogführung
• “embedded help”
Installation startet automatisch nach Download.
auf Oberfläche in Bezug
auf Testinstallation erklären
Abschluss
26 © 2
014 G
ocke, von d
er
Stü
ck
Was wir heute bearbeitet haben
Software-Doku
Normen
Zielgruppen
Informations-architektur
Entwicklungs-prozess
Informations-kanäle
27 © 2
014 G
ocke, von d
er
Stü
ck
Und jetzt was zum Merken und Weitererzählen
Prio 1: Oberfläche und die Benutzerführung verbessern, “embedded help”
Software-Dokumentation und Oberfläche gehören zusammen und beeinflussen sich
spart letztendlich Text, Zeit und somit Geld (insbs. im Hinblick auf Übersetzung)
Software-Dokumentation ist NICHT 100-Seiten PDF und gut
agiler Ansatz, interdisziplinäres Team (Entwickler, UI-Experten,
Informationsentwickler, Übersetzer, QM-Leute)
Software-Doku-Normen ISO IEC IEEE 26511 bis 26515
ISO IEC 26514 Informationsdesign. 150 Seiten. Fokussiert auf Endanwender von endlich
komplexer Software, auf gutes Schreiben und separate, meist druckbare Dokumentation.
Andere Zielgruppen (Administratoren, Entwickler, Implementierungsteam, …) und ihre Infobedürfnisse werden nur 1-2 erwähnt.
ISO IEC 26515 agile Entwicklung. 30 Seiten. Gute Einführung. Muss aber auch umgesetzt
werden Change Management!!!
28 © 2
014 G
ocke, von d
er
Stü
ck
Andrea Gocke [email protected]
Mareike von der Stück [email protected]
Ihre Meinung ist uns wichtig! Sagen Sie uns, wie Ihnen der Vortrag gefallen hat. Wir freuen uns auf Ihr Feedback per Smartphone oder Tablet unter
http://NORM13.honestly.de
oder scannen Sie den QR-Code
Das Bewertungstool steht Ihnen auch noch nach der Tagung zur Verfügung!
Informationsbedarf
(objektiv von der Zielgruppe benötigte
Information)
Informationsangebot
Informationsbedürfnis
Einflussfaktor Zielgruppe
Informationsbedarf abdecken
32 (c)
2011, S
chm
elin
g +
Consultants
Gm
bH
Unterangebot
(Fehlende
Angaben)
Überangebot
(Überflüssige
Angaben)
Angebot = Bedarf:
OK
Bedürfnis =
Bedarf: Zielgruppe
fragt nach
benötigten
Informationen
Bedürfnis nach
Informationen, die
nicht verfügbar
sind und objektiv
nicht benötigt
werden
Bedürfnis nach
Informationen, die
verfügbar sind,
aber objektiv nicht
benötigt werden
Der Weg zu Zielgruppen – wie Sie beginnen können
33 (c)
2011, S
chm
elin
g +
Consultants
Gm
bH
Daten erheben
• Befragung – mit den Leuten sprechen
• Usability-Test
• Beobachtung
• Feldstudie
• Statistische Daten über die Personenkreise, Größenordnungen von Gruppen
Zielgruppen segmentieren
• Benutzer (Rolle, Aufgaben; z.B. Hauptbuchhalter) mit den Stufen Endbenutzer und Superuser
• Admin, Hosting Team
• Implementierungsteam
• Berater
• Support
• Entwickler
• Entscheider
• …
Zielgruppen beschreiben und Konsequenzen
ableiten
• Ausbildung
• Erfahrung
• Fähigkeiten und Fertigkeiten …
• Aufgaben
• Unterschiede in Märkten und für Produktgruppen
• …
• Konsequenzen für alle Aspekte: Abbildungen, Fachwortschatz, Informationstiefe, Informationsbreite …
Maßnahmen treffen für Ihre Inhalte
• Welche Inhalte sollen bearbeitet werden?
• Stimmt das Informationsangebot?
• Maßnahmen priorisieren
• Maßnahmen exemplarisch umsetzen
• Erprobte Regeln im Redaktionsleitfaden erfassen und bekannt machen
ISO IEC IEEE 26514 DIN EN 82079-1 ISO IEC IEEE 26515
Zielgruppe • Norm: Dokuentw./-designer, Projektleiter
• Doku: Endbenutzer der Software,
marginal andere Rollen
• Norm: insb. Verantwortliche in der
Redaktion
• Doku: Benutzer des Produkts
• Norm: Dokuentw. und Projektleiter
• Doku: Benutzer, spät konkretisiert in
User roles + Personas (7.3.1, 1 S.)
Produkt • Anwendungssoftware für (End)benutzer
• Fehlt: komplexe Softwarelandschaften
alle Produkte (deutlich Herkunft aus
Maschinenbau)
Anwendungssoftware, nicht weiter
thematisiert
Prinzipien Wichtige Prinzipien (Konsistenz, …)
verteilt über die Norm
Wichtige Prinzipien (Konsistenz, …)
verteilt über die Norm
Konzepte/Ideen in agiler Entwicklung,
Vorteile und Herausforderungen
Prozesse
und Rollen
• Wasserfallmodell, Einbettung in
Softwareprozess
• 4 Phasen, u.a. Zielgruppenanalyse
• nicht explizit prof. Infoentw., aber Rollen-
beschreibungen bei Dokuevaluierung
• Fehlt: „Language Editing“ für Nicht-
muttersprachler Englisch; agile
Methoden, User Stories
• Einzelne Anforderungen an Prozess
(Risikobeurteilung, Lektorat, ...)
• Exemplarischer Erstellungsprozess im
Anhang
• Fehlt: Unterstützung zur Umsetzung
u.a. von Zielgruppenanalyse; Language
Editing für Nichtmuttersprachler Englisch
(aber Sprach-Check für Zielsprachen)
• agile Entwicklung = Fokus
• Einbettung in Softwareprozess + Teams
• agile Entwicklung: Product Design >
Planung > Entwickeln > Test+Review >
Übersetzung/Lokalisierung > Produktion
• Fehlt: Language Editing für Nicht-
muttersprachler Englisch
Info-
produkte:
Struktur,
Inhalt,
Layout
• viel allg. Info: Wort/Satz/Absatz,
Grundtypen „instruktional + referenziell“
(vgl. DITA heute), komplett/aktuell,
übersetzbar, Layout/Darstellung
• SW-Doku: Befehle, Felder, Nachrichten
• Fehlt: konkrete Info-/Dokuarten wie z.B.
Installation, Delta, Sicherheit; komplexe
Info-Dokulandschaften; Social Media
• zahlreiche detaillierte Anforderungen (Schriftgröße, Text-Bild-Nähe, Anleitung auf
Verpackung, Verhältnis zu Produktschulun-
gen, Umgang mit Sammelanleitungen, ...)
• inhaltliche Anforderungen konkret unter
dem Produktvorbehalt („if applicable“)
• Fehlt: detaillierte Formulierungshilfen,
Strukturstandards für Informationsarten
• Info-/Dokuarten nicht im Fokus
• Betont Nützlichkeit von User Stories,
Personas etc.
• kleines Manko: zu viel Gewicht auf
Dokumentation im Sinne von „topics“
und „Dokumente“, Einflussnahme auf
UI und UI-Texte wird nur kurz erwähnt
(S. 14)
Hilfsmittel Checklisten für Doku./Text und Prozesse • Checkliste zur Prüfung
• Bewertung zahlreicher empir. Methoden
Beispielhafte Fragen für Interviews,
z.B. mit Entwicklern
Werkzeuge empfiehlt CMS und Single-Sourcing keine Angaben keine Angaben
Überblick über zentrale Software-Doku-Normen Quelle dieser Folie: Vortag Software-Dokumentation – Anforderungen, Normen, Wirklichkeit (Norm 8) von der tekom
Herbsttagung 2013, gehalten von Roland Schmeling (Schmeling + Consultants GmbH) und Andrea Gocke (SAP SE)
