Dokumentation (ISO 26514) Prof. Sissi Closs Donnerstag,, 5. November 2009

Transkript

1 Der neue ISO-Standard Standard für f r Software- Dokumentation (ISO 26514) Prof. Sissi Closs Donnerstag,, 5. November 2009

2 ISO/IEC Software and systems engineering User documentation requirements for documentation designers and developers zeigt, dass Softwaredokumentation wichtig ist betont prozessorientierte Sicht: Dokumentationsprozesse müssen in den gesamten Produktlebenszyklus integriert werden Ansatz sieht unterschiedliche Rollen vor: 26514: für documentation designers and developers für manager, tester, erhebt den Anspruch, umfassend und auch für andere Bereiche als Regelwerk zu taugen

3 ISO/IEC die Fakten verabschiedet Umfang Preis Sprache 2008 als ISO-Standard 143 Seiten + Vorspann 177,00 Euro Englisch

4 ISO/IEC Ausgangsbasis Standard IEEE ISO/IEC 18019:2004 ISO/IEC 12207:2008 ISO/IEC 15288:2008 Leider fehlt DITA Wofür Standard for the design and preparation of user documentation Software and system engineering Guidelines for the design and preparation of user documentation for application software System and software engineering Software life cycle processes System and software engineering System life cycle processes Standard für topicorientierte Strukturen mit Spezialisierungen für Software und Online-Hilfe

5 ISO/IEC Inhalt Kap A-D E-G Inhalt Scope Conformance Normative reference Terms and definitions User documentation process within the system/software life cycle Project requirements, objectives, and constraints Analysis and design Development and review Production Structure of documentation Information content of user documentation Presentation format of documentation Guidelines Checklists Bibliography Seiten 2 1 0, ,5

6 ISO/IEC hat viele Schwachstellen Einige Stellen, insbesondere die Anhänge, haben eher Charakter einer Stoffsammlung. Inkonsistente Terminologie: z.b. embedded documentation, help system, entry, user documentation designer, documentation designer, designer Unpräzise Ausdrucksweise: Procedures should break down complicated ideas into simpler components so that they are explained fully.

7 ISO/IEC hat viele Schwachstellen Viele Allgemeinplätze Beispiel 6.5 Interviewing technical contacts and other experts Document designers and developers should conduct formal interviews as part of the process of gathering information and reaching consensus on design decisions. Interviews may be conducted through in-person meetings, telephone, instant messaging, , audio- or videoconferencing, Internet-based real-time chat tools, and other communication media used by the project team.

8 ISO/IEC hat viele Schwachstellen Sehr inkonsitente Beschreibungs- und Detailtiefe z. B.: relativ ausführlich Procedure: 2,5 Seiten knapp für Tutorial: 1 Absatz Darstellungsaspekte zu printlastig und im Verhältnis zu detailliert z.b. Annex D:13 Seiten über Design of printed documentation aber nichts zu elektronischer Darstellung Beispiele willkürlich

9 ISO/IEC hat viele Schwachstellen Besonderheiten der Software-Doku fehlen: Auswirkungen der besonderen Produkteigenschaften von SW (Terminologie, Umgang mit Fehlermeldungen, ) Reference mode documentation shall include each error message with an identification of the problem, probable cause, and corrective actions that the user should take. besondere Möglichkeiten bedingt durch elektronisches Umfeld (Zugang, Verlinkung, Mutimedia, Nutzereinbeziehung, ) spezifische Inhalte (z. B. Screenshots) spezifische Vorgehensweisen (agil, iterativ) geeignete Strukturierungsansätze (modular, topicorientiert)

10 ISO/IEC Bewertung Betonung des Stellenwerts der SW-Doku prozessorientierte Sicht Berücksichtigung unterschiedlicher Rollen Berücksichtigung von kommerziellen Aspekten Besonderheiten der SW-Doku nicht erkennbar keine Berücksichtigung agiler Vorgehensmodelle Belange der Doku-Entwicklung nicht ausreichend abgedeckt Ebenen nicht eingehalten veraltete Ansätze

11 Resumé Dokument ist die Bezeichnung Standard nicht wert und schon gar nicht den Preis Es gibt andere Quellen, um Vorgehensweise und Qualität auf verlässliche Basis zu stellen, z.b.: Gretchen Hargis: Developing Quality Technical Information ISO/IEC kann als Referenz dienen, keinesfalls aber als praxistauglicher Redaktionsleitfaden. Einzelne, passende Empfehlungen müssen herausgegriffen und für das eigene Umfeld konkretisiert und vertieft werden.

12 Fragen? Vielen Dank Gerne laden wir Sie auf unseren Stand ein: Halle 3, 301/302