Software-Dokumentation Anforderungen, Normen, Wirklichkeit (Norm 8)

Transkript

1 Software-Dokumentation Anforderungen, Normen, Wirklichkeit (Norm 8) NORM Gesetze, Normen und Richtlinien tekom Jahrestagung, 7. November 2013, Wiesbaden Roland Schmeling (Schmeling + Consultants GmbH) Andrea Gocke (SAP AG)

2 Agenda Begriffsklärungen Normen und andere Rahmenbedingungen Da steh ich nun, ich armer Tor! Und bin so klug als wie zuvor. Die zentralen Normen für Softwaredokumentation Und wie helfen diese Normen in der Wirklichkeit? Antworten aus Sicht der SAP Zusammenfassung und Empfehlungen

3 1 Begriffsklärungen

4 Software-Dokumentation: Aspekte zur Klassifikation Die Anforderungen an Software-Doku hängen von vielen Faktoren ab Software Prozess (c) 2013, Schmeling + Consultants GmbH Nähe zum Anwender: Systemsoftware systemnahe Software Anwendungssoftware (Schwerpunkt) Produktart: Software als eigenständiges Produkt (z. B. Office-Anwendung, ERP-Software) oder Software im Produkt (z.b. Maschinensteuerung) Standardisierungsgrad: Standard-Software hochkonfigurierbare Software Individual- Software Komplexitätsgrad: gering hoch Branche: branchenspezifisch breite Branchenabdeckung branchenunabhängig bei Software im Produkt z.b. Maschinenbau, Medizinprodukte, bei Software als eigenständiges Produkt, z.b. Software für Banken, Steuerberatung, öffentliche Verwaltung Organisationsgrad des Software-Herstellers, u.a. Qualitätsmanagement: gering hoch Methode der Software-Entwicklung: Wasserfall oder agile Methoden (XP, SCRUM) Lieferanten: Entwicklungspartner, eigenständige integrierbare Produkte von Partnerunternehmen, mitgelieferte OEM-Software Anleitung Informationsproduktarten: Verwendung der Informationen in Informationsprodukten für Zielgruppen (Installationsleitfaden, Betriebsanleitung,...); speziell externe vs. interne Dokumentation Informationsarten: inhaltlich (Installation, Konfiguration, Bedienung,...) oder funktional (Anleitung/Task Mode, Beschreibung/Concept, Nachschlageinformation/ Reference Mode,...) Medien: gedruckt, elektronische Formate 4

5 Begriffsklärungen Produktart bei Anwendungssoftware (c) 2013, Schmeling + Consultants GmbH Software als eigenständiges Produkt unabhängig von einem Produkt (abgesehen vom Rechner) wird teilweise vom Anwender oder von Spezialisten installiert geringes Sicherheitsrisiko Ausnahmen, z. B. Software in der medizinischen Diagnostik: Risiko der Fehldiagnose Vertragsrecht Software im Produkt in ein Produkt eingebettet wird in der Regel vom Produkthersteller installiert abhängig vom Produkt: Gefahr für Sicherheit und Gesundheit von Anwendern und Dritten Risiken gehen vom Produkt aus Software kann (mit)ursächlich für Gefährdung sein und die Haftung begründen Produktsicherheitsrecht Produkthaftungsrecht Produktsicherheitsnormen Vertragsrecht 5

6 Begriffsklärungen Standardisierung Standardsoftware Individualsoftware Gedanke des Produkts naheliegend Werk, oft in enger Kooperation mit dem Kunden, ggf. gemeinsame Entwicklung in der Regel Kaufvertrag über Lizenzen (Nutzungsrechte) Werkvertrag naheliegend Weiterverkauf gebrauchter Software unter best. Voraussetzungen möglich Software eng auf einen konkreten Bedarf hin entwickelt (c) 2013, Schmeling + Consultants GmbH nicht grundsätzlich ausschließbar Weiterverkauf in der Regel praktisch ausgeschlossen 6

7 Begriffsklärungen interne und externe Dokumentation ISO IEC IEEE 15289:2011 Software und System-Engineering Content of life-cycle information products (documents) Interne Dokumentation (Spezifikationen, ) Anwenderdokumentation User documentation System architecture description Interface description (c) 2013, Schmeling + Consultants GmbH Software requirements specification Change request Validation test specification Concept of operation Documentation plan Information management plan User documentation User notification Training documentation 7

8 2 Normen und andere Rahmenbedingungen

9 Normen mal ganz allgemein Normen und Standards (für Softwaredokumentation) neutral (nicht proprietär) werden von Normungsorganisationen erarbeitet und publiziert entstehen durch Input und Abstimmung von verschiedenen Interessengruppen sehr umfassend, heterogene Granularität eigene Situation analysieren und Umsetzungsentscheidungen treffen enthalten Muss- und Kannanforderungen (shall, should, may) Produktanforderungen (Inhalt, Struktur, Layout) Prozessanforderungen (Phasen im Entwicklungsprozess, Rollen) ermöglichen eine leichtere und bessere Zusammenarbeit im und mit anderen Unternehmen machen Produkte und Prozesse vergleichbar ermöglichen es, Verbesserungspotential zu identifizieren Grundlage für Verträge und Audits STÄRKE UND SCHWÄCHE! 2013 SAP AG. All rights reserved Schmeling + Consultants GmbH 9

10 Rechtlicher Rahmen (abhängig von der jeweiligen Rechtsordnung) Normen User Anforderungen an Produkt incl. Software und Information: Benutzbarkeit, Gebrauchstauglichkeit, Barrierefreiheit (End user, Admin, Power user,) Anwendungssituation: Aufgaben Qualitätsforderungen an die Dokumentation: vollständig, verankert, verständlich, vertrauenswürdig EULA AGB Produkt Produktentwicklung Unternehmen User Interface User Documentation separat eingebettet Oberflächentext E-Learning Terminologie, Indexierung Visualisierung, Medien Informationskonzept Info-Design/ Doku-/Infolandschaft/ Standardisierung Strategische Ziele, Ressourcen, Organisation Lokalisierung Übersetzung Analyse, Konzept, Erstellung, Produktion, Test, Aktualisierung, Software Erstellungs prozess Agile Methoden SCRUM interne Dokumentation (z.b. Spec), Software-Lebenszyklus; Systemlandschaft Software + System Branchenspezifische Regeln, z. B. International Financial Reporting Standards (IFRS), Grundsätze DV-gestützter Buchführungssysteme (GoBS) Qualitätsmanagementsysteme Lieferanten Gesetze + Rechtsprechung Produkthaftung Vertragsrecht Produktsicherheit Verbraucherschutz 10

11 Normen und andere Rahmenbedingungen Primärinformationen Software Engineering ISO IEC Systems and software engineering - Software life cycle processes Kapitel Software Documentation Management Process wird in ISO aufgegriffen und detailliert behandelt. ISO IEC Systems and software engineering - System life cycle processes ISO IEC IEEE Systems and software engineering. Content of life-cycle information products (documentation) Softwaredokumentation Systems and software engineering (Normenreihe) ISO IEC IEEE Systems and software engineering - Requirements for managers of user documentation ISO IEC IEEE Systems and software engineering - Requirements for acquirers and suppliers of user documentation ISO IEC IEEE Systems and software engineering - Requirements for testers and reviewers of user documentation ISO IEC IEEE Systems and software engineering - Requirements for designers and developers of user documentation ISO IEC IEEE Systems and software engineering - Developing user documentation in an agile environment DIN Informationstechnik - Bewerten von Softwaredokumenten - Qualitätsmerkmale ISO IEC Preparation of instructions for use - Structuring, content and presentation - Part 1: General principles and detailed requirements [Anm.: allgemeine Dokumentationsnorm, nicht speziell Softwaredokumentation]; deutsch: DIN EN Content Management ISO IEC CD Content management for product life-cycle, user and service management documentation Industry Standards, Open Source DITA, OASIS, W3C Grundsätze ordnungsmäßiger DV-gestützter Buchführungssysteme (GoBS) Kapitel 6 Dokumentation und Prüfbarkeit, emen/betriebspruefung/015.pdf International Financial Reporting Standards (IFRS) Commercial Off-The-Shelf software products ISO IEC Software engineering. Software product Quality Requirements and Evaluation (SQuaRE). Requirements for quality of Commercial Off-The-Shelf (COTS) software product and instructions for testing 2013 SAP AG. All rights reserved Schmeling + Consultants GmbH 11

12 Normen und andere Rahmenbedingungen Primärinformationen Gebrauchstauglichkeit, Ergonomie, Barrierefreiheit (1/2) Die ISO-9241-Reihe (Arbeitsumgebung, Hardware, Software) Ca. 40 Einzelnormen, Richtlinien für Mensch-Computer-Interaktion, daher Titel der Normenreihe seit 2006 Ergonomie der Mensch- System-Interaktion. EU-Rechtsprechung: EN ISO 9241 ist Standard zur Bewertung der Benutzerfreundlichkeit aus der Bildschirmarbeitsverordnung (BildscharbV). [Quelle: DIN EN ISO Ergonomic requirements for office work with visual display terminals (VDTs) - Part 11: Guidance on usability (ISO :1998) Gebrauchstauglichkeit von Software aus Nutzersicht: Effektivität bzgl. Aufgabebewältigung, Effizienz bzgl. Handhabung, Zufriedenheit DIN EN ISO Ergonomics of human-system interaction - Part 110: Dialogue principles Grundsätze für die Gestaltung und Bewertung einer Schnittstelle zwischen Benutzer und System: Aufgabenangemessenheit, Selbstbeschreibungsfähigkeit (Orientierung, z.b. bread crumbs; Beherrschbarkeit, z.b. Navigationselemente; Rück-/ Erfolgsmeldungen; Hilfestellung, z.b. Mouseover), Lernförderlichkeit, Steuerbarkeit, Erwartungskonformität, Individualisierbarkeit, Fehlertoleranz (Ziel wird trotz fehlerhafter Eingaben erreicht, kein/min. Korrekturaufwand seitens Benutzer, z.b. Fehlererläuterung, automatische Korrektur) DIN EN ISO Ergonomics of human-system interaction - Part 210: Human-centred design for interactive systems DIN EN ISO Ergonomics of human-system interaction - Part 171: Guidance on software accessibility Ergonomics guidance and specifications for the design of accessible software for use at work, in the home, in education and in public places. It covers issues associated with designing accessible software for people with the widest range of physical, sensory and cognitive abilities, including those who are temporarily disabled, and the elderly... it does address the use of assistive technologies as an integrated component of interactive systems [Quelle: SAP AG. All rights reserved Schmeling + Consultants GmbH 12

13 Normen und andere Rahmenbedingungen Primärinformationen Gebrauchstauglichkeit, Ergonomie, Barrierefreiheit (2/2) Barrierefreiheit (zusätzlich zu DIN EN ISO Software Accessibility) ISO IEC Information technology - W3C Web Content Accessibility Guidelines (WCAG) (siehe auch Freely Available ISO Standards, Section 508 Amendment to the Rehabilitation Act of Verordnung zur Schaffung barrierefreier Informationstechnik nach dem Behindertengleichstellungsgesetz (Barrierefreie- Informationstechnik-Verordnung - BITV 2.0) Multimedia ISO Software ergonomics for multimedia user interfaces - Part 1: Design principles and framework (ISO :2002) ISO Software ergonomics for multimedia user interfaces - Part 2: Multimedia navigation and control (ISO :2003) ISO Software ergonomics for multimedia user interfaces - Part 3: Media selection and combination (ISO :2002) Human Interface Guidelines Human Interface Guidelines (Wikipedia-Artikel) mit Links auf die jeweiligen Guidelines Beispiele: Android User Interface Guidelines, Apple ios Human Interface Guidelines, Eclipse User Interface Guidelines, Java Look and Feel Design Guidelines, SAP Design Guild 2013 SAP AG. All rights reserved Schmeling + Consultants GmbH 13

14 Normen und andere Rahmenbedingungen Primärinformationen Quality Management DIN EN ISO 9001 Quality management systems Requirements Gesetze und Rechtsprechung Verbraucherschutz Produkthaftungsrecht Produktsicherheitsgesetz Vertragsrecht Firmenspezifische Rahmenwerke Allgemeine Geschäftsbedingungen Verträge (z.b. Endbenutzer-Lizenzvertrag) Qualitätsmanagementsysteme (als Umsetzungen von ISO 9001) Prozessstandards Produktstandards Schreibrichtlinien und Templates (allgemein versus für best. Dokuarten und Zielgruppen) 2013 SAP AG. All rights reserved Schmeling + Consultants GmbH 14

15 Normen und andere Rahmenbedingungen Sekundärinformationen zum Einlesen Grünwied, Gertrud (2009): Softwaredokumentation gewinnt an Bedeutung. In: technische kommunikation, Ausgabe 4, S (auch auf der tekom-webseite verfügbar) Grünwied, Gertrud (2013): Ein vielfältiges Spektrum. In: technische kommunikation, Ausgabe 3, S (auch auf der tekom-webseite verfügbar) Vogler, Daniela (2013): Agil dokumentieren. In: technische kommunikation, Ausgabe 3, S (auch auf der tekom-webseite verfügbar) Schmeling, Roland (2011): Normen und Medien. In: Hennig, Jörg und Tjarks-Sobhani, Marita (Hrg.): Veränderte Mediengewohnheiten andere Technische Dokumentation? (= tekom-schriften zur Technischen Kommunikation 15), S tekom e.v.: tekom-normenkommentar unter Gesetze und Normen Normenkommentar (Login erforderlich) Webseiten der diversen Normungsorganisationen (beinhalten Kurzbeschreibungen oder Inhaltsverzeichnisse) Wikipedia (englische und deutsche Artikel zu Normen etc.) 2013 SAP AG. All rights reserved Schmeling + Consultants GmbH 15

16 3 Da steh ich nun, ich armer Tor! und bin so klug als wie zuvor [Goethe, Faust I]

17 Sollen wir die Normen kaufen? Welche? Woran sollen wir uns wie halten? Ist das alles gleich relevant? Wie setzen wir die Anforderungen um? Wann? Was haben wir davon? Was bedeutet das? Trifft das auf uns zu? 2013 SAP AG. All rights reserved Schmeling + Consultants GmbH 17

18 Wo ist der Nutzen im Redaktionsalltag? Zielgruppen Informationsprodukte: Doku-/Infoarten (Inhalt, Struktur, Layout) Infoentwickler Software (Produkt) Prozesse und Rollen Dokumentationswerkzeuge (z.b. CMS, Term-Datenbank) 2013 SAP AG. All rights reserved Schmeling + Consultants GmbH 18

19 4 Die zentralen Normen für Softwaredokumentation ISO IEC IEEE DIN EN (IEC ) ISO IEC IEEE ISO IEC 15289

20 ISO IEC IEEE Systems and software engineering Requirements for designers and developers of user documentation 154 Seiten Schwerpunkt und Grundaussagen supports the interest of software users in consistent, complete, accurate, and usable documentation [S. 1] Auch anwend-/übertragbar u.a. für: weitere Zielgruppen (z.b. Administratoren, Implementierungsteam), Systemdokumentation Prozessstandards: Doku als integraler Bestandteil des Softwareentwicklungsprozesses, Phasen Planung Auslieferung / Update Produktstandards: Struktur, Inhalt, Layout ( presentation format ); product = complete set of software and documentation Dokumentationswerkzeuge: tool-neutral, empfiehlt Content- Management-System + Topic-Orientierung Dokumentationsmedien: Bildschirmanzeige und gedruckt/druckbar Bezug zu anderen Normen ISO IEC Systems and software engineering Software life cycle processes: Kapitel Software Docu. Mngment Process ISO IEC Systems and software engineering - System life cycle processes: Kapitel Information Management Process, Doku-Designer sind Teil dieses Prozesses ISO IEC Systems and software engineering Content of systems and software life cycle process information products (Documentation): erwähnt interne Doku. aus Softwarelebenszyklus (z.b. Dokumentationsplan, Designdokumente) 2013 SAP AG. All rights reserved Schmeling + Consultants GmbH 20

21 Was bietet die Norm? ISO IEC IEEE Requirements for designers and developers of user documentation Struktur: Gesamtdokumentation- Einzeldokumente, Zielgruppen, instructional + reference mode, Informationsprofil, Topicgröße, Dokumentationsbestandteile (z.b. Inhaltsverzeichnis, Einleitung, Glossar) Inhalt: komplett, genau, aktuell; Identifikationsdaten; Hintergründe/Konzepte/Einbettung für jew. Benutzer; instructional mode (Anweisungen + Konzepte), reference mode ; etwas Info zu Info-/Dokuarten Befehle, Felder, Fehler, Terminologie Layout (Darstellung): Druck - Bildschirm, Barrierefreiheit, konsistente Terminologie, Layout/Typographie, Navigation/Orientierung, Hinweise, Benutzerinhalte, Grafiken Checklisten im Appendix Dokumentation ist Bestandteil des Softwareentwicklungsprozesses keine Forderung nach profess. Infoentwicklern ("whether or not a dedicated documentation department is present [...]. Readers are assumed to have experience or knowledge of software development or documentation development processes.") Wasserfallmodell mit folgenden Phasen: 1.Projektanforderungen, Ziele, Einschränkungen: Wofür ist die Software? Zielgruppen? Releaseplanung? Tools? Gebrauchstauglichkeit, Benutzbarkeit? Barrierefreiheit? Übersetzungen? Lokalisierung? QM? 2.Analyse und Design: Zielgruppen und Aufgaben? Informationsbedarf? Nutzungskontext? Medien/Formate? Ergebnis: Dokukonzept, Redaktionsleitfaden, Dokuplan 3.Dokuentwicklung und -prüfung: Gemäß Dokuplan. Prüfen und Testen von Inhalten, Verständlichkeit, Vollständigkeit, Konsistenz, Formalien auch mit der Software. Rollen: Autor, Editor, Entwickler, Manager, Benutzer 4.Produktion inkl. Aktualisierung: Produktion, Publikation, Auslieferung, Aktualisierung Checkliste im Appendix Fokus auf Endbenutzer, d.h. Rollen, die mit der Software ihre Aufgaben erledigen andere Rollen (z.b. Admin, Entwickler, Implementierer) nur marginal Fokus auf Anwendungssoftware, nicht zu komplex Neutral - empfiehlt CMS und Single-Sourcing 2013 SAP AG. All rights reserved Schmeling + Consultants GmbH 21

22 DIN EN :2013 (ISO IEC :2012)* Erstellen von Gebrauchsanleitungen Gliederung, Inhalt und Darstellung Teil 1: Allgemeine Grundsätze und ausführliche Anforderungen 58 Seiten Schwerpunkt und Grundaussagen allgemein, nicht speziell für Softwaredokumentation: für alle Arten von Produkten, von der Dose Farbe bis zur Industrieanlage [S. 8] Produktstandards: Prinzipien: Gebrauchsanleitungen sind Teil des Produkts; Verfügbarkeit, Konsistenz, Gebrauchsanleitungen: Schriftgröße, Sicherheits- und Warnhinweise, Druck/elektronisch, funktionale Formulierung, Prozess: Risikobeurteilung, Redaktionsleitfaden, Qualitätssicherung, Konformitätsprüfung, empirische Methoden, Wichtige betrachtete Produktbereiche: Verbraucherprodukte, Maschinen, Geräte Wichtige Referenzen zu anderen Normen (Auszug) IEC Graphical symbols for use on equipment ISO 3864 (all parts) Graphical symbols Safety colours and safety signs ISO 7010 Graphical symbols Safety colours and safety signs Registered safety signs ISO 9241 (all parts) Ergonomics of human-system interaction ISO Packaging Tactile warnings of danger Requirements ISO Safety of machinery General principles for design Risk assessment and risk reduction 2013 SAP AG. All rights reserved Schmeling + Consultants GmbH * Löst IEC 62079:2001 ab (Übergangsfrist bis 2015) 22

23 Was bietet die Norm? DIN EN Erstellen von Gebrauchsanleitungen Gliederung, Inhalt und Darstellung Teil 1: Allgemeine Grundsätze und ausführliche Anforderungen inhaltliche Anforderungen an bestimmte Informationsarten, z.b. Montageinformation, Wartungsinformation zahlreiche konkrete Anforderungen an die Darstellung Forderung nach Zielgruppenanalyse (ohne Ausführung des Wie) Verweis auf produktspezif. Anforderungen, insb. Produktsicherheitsnormen verantwortliche Redakteure und Autoren mit Anforderungen an die Qualifikation, Lektoren, Übersetzer, Illustratoren usw. Beispiel für Erstellungsprozess im Anhang Übersicht über empirische Methoden mit Vor- und Nachteilen große internationale Beachtung als Normenreihe angelegt Weiterarbeit national und international angestoßen Tipp: tekom- Normenkommentar nutzen 2013 SAP AG. All rights reserved Schmeling + Consultants GmbH 23

24 ISO IEC IEEE Systems and software engineering Developing user documentation in an agile environment 36 Seiten Schwerpunkt und Grundaussagen Prozessstandards: supports the interest of technical writers and associated roles [ ] within an agile environment. [ ] a process standard approach to specify the way in which user documentation can be developed in agile development projects. [S.1] Software ist nur mit Dokumentation vollständig: In agile development, the software cannot be considered complete without the production and validation of the associated user documentation. [S. 14] Bezug zu anderen Normen ISO IEC Systems and software engineering Software life cycle processes ISO IEC Systems and software engineering - System life cycle processes ISO IEC IEEE 2651n Normenreihe 2013 SAP AG. All rights reserved Schmeling + Consultants GmbH 24

25 Was bietet die Norm? ISO IEC IEEE Developing user documentation in an agile environment Info-/Dokuarten oder Dokulandschaft sind nicht Fokus dieser Norm betont die Wichtigkeit und Nützlichkeit interner Dokumentation wie z.b. Sprint Plan, User Story, Persona keine Vorgaben zu agilen Entwicklungsmethoden Einführung in wichtige Aspekte der agilen Entwicklung aus Dokumentationssicht: Konzepte: iterativ, inkrementell, interdisziplinär, selbstorganisierend, direkte Kommunikation statt Massen an interner Doku, Sprints (incl. Vorlauf und Rückblick), Scrum-/Statusmeetings Vorteile für Autoren: früh und direkt involviert (Entw., UI, Tester, ; Artefakte) statt Silos, direktes Feedback, Software + UI beeinflussen Herausforderungen: versch. Entwicklungsstandorte, Featureentwicklung in Sprints vs. Gesamtdokumentation (z.b. Installationsleitfaden oder Troubleshooting-Information können erst später geschrieben werden) Benutzer ( user ) Benutzertyp/Zielgruppe ( audience ) category of users sharing the same or similar characteristics and needs [ ] that determine content, structure, and use [ ] Rollen und Personas mit Zielen, Aufgaben, Fähigkeiten (z.b. Web-Entwickler, Administrator, Laborassistent) User Story As a (role), I want (goal), so that I can (business value). Sonst: Use Case, Scenario Dokumentationswerkzeuge (z.b. CMS) werden nicht behandelt Anwendungssoftware (1 x in Introduction erwähnt, nicht weiter thematisiert) keine Vorgaben zu Werkzeugen (tools) für agile Entwicklung 2013 SAP AG. All rights reserved Schmeling + Consultants GmbH 25

26 ISO IEC IEEE keine Handlungsinstruktionen Systems and software engineering Content of life-cycle information products (documentation) 94Seiten Schwerpunkt und Grundaussagen Hauptzielgruppe: Projektmanager, die für das Informationsmanagement gemäß ISO IEC IEEE verantwortlich sind Inhalt: interne Dokumente im Entwicklungszyklus Grundtypen: plan, policy, procedure, report, request, specification alphabetische Auflistung der einzelnen Arten (ca. 90) interessant als Input für (externe) Dokumentation: documentation plan, information management plan, installation plan/report, integration plan/report, interface description, security plan, software architecture description, software design description, software requirements specification, system architecture description, user documentation Bezug zu anderen Normen ISO IEC Systems and software engineering Software life cycle processes ISO IEC Systems and software engineering - System life cycle processes 2013 SAP AG. All rights reserved Schmeling + Consultants GmbH 26

27 Da steh n wir nun sind jetzt aber klüger in Bezug auf ISO IEC IEEE 26514, ISO IEC IEEE und DIN EN ISO IEC IEEE DIN EN ISO IEC IEEE Zielgruppe Norm: Dokuentw./-designer, Projektleiter Doku: Endbenutzer der Software, marginal andere Rollen Produkt Prinzipien Prozesse und Rollen Infoprodukte: Struktur, Inhalt, Layout Hilfsmittel Anwendungssoftware für (End)benutzer Fehlt: komplexe Softwarelandschaften Wichtige Prinzipien (Konsistenz, ) verteilt über die Norm Wasserfallmodell, Einbettung in Softwareprozess 4 Phasen, u.a. Zielgruppenanalyse nicht explizit prof. Infoentw., aber Rollenbeschreibungen bei Dokuevaluierung Fehlt: Language Editing für Nichtmuttersprachler Englisch; agile Methoden, User Stories 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 Norm: insb. Verantwortliche in der Redaktion Doku: Benutzer des Produkts alle Produkte Wichtige Prinzipien (Konsistenz, ) verteilt über die Norm 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) Norm: Dokuentw. und Projektleiter Doku: Benutzer, spät konkretisiert in User roles + Personas (7.3.1, 1 S.) Anwendungssoftware, nicht weiter thematisiert Konzepte/Ideen in agiler Entwicklung, Vorteile und Herausforderungen agile Entwicklung = Fokus Einbettung in Softwareprozess + Teams agile Entwicklung: Product Design > Planung > Entwickeln > Test+Review > Übersetzung/Lokalisierung > Produktion Fehlt: Language Editing für Nichtmuttersprachler Englisch zahlreiche detaillierte Anforderungen Info-/Dokuarten nicht im Fokus (Schriftgröße, Text-Bild-Nähe, Anleitung auf Betont Nützlichkeit von User Stories, Verpackung, Verhältnis zu Produktschulungen, Umgang mit Sammelanleitungen,...) Personas etc. kleines Manko: zu viel Gewicht auf inhaltliche Anforderungen konkret unter Dokumentation im Sinne von topics dem Produktvorbehalt ( if applicable ) und Dokumente, Einflussnahme auf Fehlt: detaillierte Formulierungshilfen, UI und UI-Texte wird nur kurz erwähnt Strukturstandards für Informationsarten (S. 14) Checklisten für Doku./Text und Prozesse Checkliste zur Prüfung Bewertung zahlreicher empir. Methoden Werkzeuge empfiehlt CMS und Single-Sourcing keine Angaben keine Angaben Beispielhafte Fragen für Interviews, z.b. mit Entwicklern 2013 SAP AG. All rights reserved Schmeling + Consultants GmbH 27

28 5 Und wie helfen diese Normen in der Wirklichkeit? Antworten aus Sicht der SAP

29 Über SAP SAP Zu den SAP-Kunden gehören 86% der Global Fortune 500 und 98% der wertvollsten Marken. 80% der Kunden sind KMUs in 120 Kunden Ländern SAP-Mitarbeiter weltweit 100 Entwicklungsstandorte 25 x 11 Software für Industrien x Geschäftsbereiche 5 Marktkategorien (Anwendungen, Analytik, Mobilität, Datenbanken & Technologie (SAP HANA), Cloud) Dokumentation und Übersetzung Seitenaufrufe / Jahr auf dem SAP Help Portal 700 Infoentwickler + Übersetzer 400+ Produktversionen auf dem SAP Help Portal 37 Oberflächensprachen 9 Dokumentationssprachen (je nach Produkt) help.sap.com 2013 SAP AG. All rights reserved. 29

30 Software-Dokumentation: Aspekte zur Klassifikation Wo ist einzuordnen? Software im/als Produkt im Produkt als Produkt Software Prozess Text Nähe zum Anwender Standard-/Individualsoftware Komplexitätsgrad Software Branche Methode Softwareentwicklung Organisationsgrad Hersteller Lieferanten der Software Komplexitätsgrad Text Informationsarten (Topic + höher) Phys. Dokumente (z.b. InstLeitfaden) Systemsoftware systemnahe Software Anwendungssoftware individuell hochkonfigurierbar Standard Gering (Apps) mittel (mit Hosting) hoch (on premise) spezifisch breite Branchenabdeckung unabhängig Wasserfall gemischt agil gering mittel hoch OEM-Software Partnerprodukte SAP Kurztext (auf UI) Topic Hierarchie funkt. Grundtypen (einfach) typische Einzelfälle übergeord. Zweck (komplex) (z.b. Task, Concept, Reference) (z.b. Feldhilfe) (z.b. Installation, Sicherheit) int./ext. Verwendung Überblick Zielgruppen Stückliste mit int./ext. ZGr 2013 SAP AG. All rights reserved. 30

31 Normen: Wo ist der Nutzen im Redaktionsalltag? Informationsprodukte: Doku-/Infoarten (Inhalt, Struktur, Layout) Zielgruppen Infoentwickler Software (Produkt) Prozesse und Rollen Dokumentationswerkzeuge (z.b. CMS, Term-Datenbank) 2013 SAP AG. All rights reserved. 31

32 Prozesse und Rollen Idea to Market (I2M) Dokumentation ist Bestandteil des Entwicklungsprozesses Prozess Idea to Market (I2M) mit Subprozess Write and translate product documentation + Produktstandard Produktdokumentation agile Entwicklung, Lean, Scrum, Backlog, Design Thinking, User Stories, Kundenkontaktprogramme Dokumentationsprodukte sind automatisch im Backlog SAP ist ISO-9001-zertifiziert, PVG Audit 2011 high standard des Doku-/Übersetzungsprozesses Funktionen und Rollen/Aufgaben Informationsentwickler (SAP-Begriff für techn. Redakteur ) Übersetzer Knowledge Manager für Infoentwickler und Übersetzer Knowledge Architect (Dokulandschaft, KM BOM) KM-Vertreter im Produktteam Product Standard Owner und pro Bereich Experten Copy, Language und Developmental Editor (Formal/Sprache und Inhalt/Struktur) Power User für Tools (SAPterm, SAP KW, DITA, ) Grafiktraining für Infoentwickler und Übersetzer (Tester und Validierer im Rahmen der Solution Validation) Jobprofile mit versch. Stufen (z.b. Senior, Knowledge Architect) zentraler Recruitingprozess, Tests Rollen und Aufgaben 2013 SAP AG. All rights reserved. 32

33 SAP-Dokumentations- und Übersetzungsprozess Write and translate product documentation Prozessmodell Portfolio to Planning (Quality gate, toolgestützt)* * Alle Produkte müssen alle Produktstandards erfüllen, nicht nur Produktdokumentation. Planung (z.b. Doku-/Infoprodukte, Qualitätsmaßnahmen) Planning to Development (s.o.) Erstellung / Entwicklung KM Produktteam KM Scrum-Team 1 Lean, Scrum, KM Scrum-Team n Development to Production (s.o.) Produktion (z.t. eigene Abteilungen, z.t. Infoentwickler) Production to Ramp-Up (s.o.) 2013 SAP AG. All rights reserved. 33

34 Dokumentation als integraler Bestandteil des Softwareentwicklungsprozesses Input zu <Info- /Dokuart> geben Produktteam (z.b. Entwickler) <Info-/Dokuart> erstellen und Inhalt verifizieren Autor (Infoentwickler) 2013 SAP AG. All rights reserved. 34

35 Weitere Prozesse, insb. Qualitätsmaßnahmen Language Editing für Nichtmuttersprachler Englisch (Entwickler und Infoentwickler) Copy Editing Developmental Editing Quality Circles Terminologie Reviews (Superuser-Konzept) Product Standard Assessments (Documentation Health Checks) Standards & Guidelines Consulting SAP Help Portal (help.sap.com) Feedbackfunktion Customer Feedback Program User Stories Design Thinking 2013 SAP AG. All rights reserved. 35