SEQIS, der führende österreichische Anbieter in den Spezialbereichen Software Test und IT Analyse, schöpfte wieder einmal aus dem Vollen des umfangreichen Erfahrungsschatzes der Experten. Vinzenz Preiss verriet im Rahmen eines Fachvortrages seine persönlichen 10 Tipps und Tricks zur richtigen und sinnvollen Dokumentation in IT-Projekten.
Sinnvolle und richtige Dokumentation ist das Grundgerüst jedes IT-Projekts. Dokumentation dient der effektiveren Zusammenarbeit und der Verfolgung wirtschaftlicher Ziele. Damit Dokumente ihren Zweck erfüllen, müssen schon zu Beginn folgende Überlegungen getroffen werden: Wer ist die Zielgruppe der Dokumentation (Stakeholder)? Wofür soll das Dokument stehen (Nutzen)? Ist das Dokument valide und messbar?
Doch wie viel Dokumentation ist wirklich notwendig? Und wie kann die Zusammenarbeit von Fachseite und IT-Spezialisten bei der Dokumentation erfolgen, obwohl Sprachgebrauch und Werkzeuge gänzlich unterschiedlich sind? Vinzenz Preiss hat dafür 10 praxisnahe Expertentipps parat, die er im Rahmen eines Expertentreffs den zahlreichen Teilnehmern weitergab:
Tipp 1: Jedes Dokument muss messbar den Nutzen einer Zielgruppe erfüllen
Beim Schreiben wird selten ein kritischer Blick auf das Erfolgspotenzial des Dokuments geworfen. Zu schnell öffnet sich ein Editor und es wird darauf losgetippt. Wenn dabei zu viel Aufwand investiert wird, der ohne Gegenwert bleibt, wurde waste produziert. Wenn überhaupt, wird das erst, nachdem der Aufwand schon getrieben wurde, erkannt.
Nehmen Sie sich daher die Zeit und definieren Sie die Berechtigung für die Existenz des Dokuments bevor Sie mit der Ausarbeitung beginnen: Definieren Sie die Zielgruppe Ihres Dokuments. Überlegen Sie sich, welches Problem dieser Zielgruppe das Dokument löst. Ohne Empfänger oder dessen Nutzen genau zu kennen gibt es keinen Grund, Arbeit zu investieren. Verifizieren Sie Ihre Annahmen durch Messungen. Nur so können Sie leere Kilometer vermeiden (waste) und Wertvolles absichern.
Tipp 2: Starten Sie Ihr Dokument früh, detaillieren Sie es jedoch spät
Der Product Life Cycle (PLC) umfasst zahlreiche Phasen zur Erstellung und zum Betrieb eines Software-Produkts. Entlang dieses Prozesses reift das Produkt und verändert sich, bis es schließlich seinen definierten Zweck erfüllen kann. In diesen Phasen gibt es auch zahlreiche Dokumente, die auf unterschiedliche Weise nützlich sind.
Genauso muss auch ein Dokument erst Phasen der Reifung durchlaufen, ehe es von Nutzen ist. Machen Sie sich bewusst, welchen Lauf der Document Life Cycle (DLC) nimmt. Synchronisieren Sie den DLC mit relevanten Meilensteinen des PLC, um Informationen rechtzeitig zu liefern. Auch ein Dokument erfordert Zeit und Arbeit zum Entstehen.
Unterstützen Sie diesen Prozess durch frühe Stichworte und validieren Sie inhaltliche Eckpunkte. Formulieren Sie aber erst möglichst spät aus. Je später Sie Ihre Beschreibung in die finale Form bringen, desto geringer ist die Gefahr von unerwünschtem Änderungsaufwand.
Tipp 3: Dokumentieren Sie wiederverwendbar
Bei der Beschreibung – speziell in Textform – wird häufig ein Ablauf skizziert. Weil der gewünschte Endzustand fokussiert wird, wird dieser direkt beschrieben. Dahinterliegende Implementierungen sind jedoch meist objektorientiert aufgebaut. Sie sind wiederverwendbar und können mehrere Szenarien ohne erneute Implementierung abbilden.
Auch Dokumentation kann objektorientiert gestaltet werden. Wenn Sie Generisches von Szenarien trennen, haben Sie die Möglichkeit zur Wiederverwendung.
Durch Labels lassen sich generische Beschreibungen mit einem Kontext markieren. Bei Aufruf des Labels wird automatisch eine Dokumentation für diesen einen Kontext erstellt, ohne dass für jedes Stichwort eigene Dokumente existieren. Es gibt nur ein Original. Dadurch entfällt die Gefahr von Fehlern durch Redundanz und Beschreibungsanomalien.
Tipp 4: Übersichtlichkeit zählt vor Details
Um Menschen Information zugänglich zu machen, muss diese Information erst einmal gefunden und als relevant erkannt werden. Inhaltliche Abhandlungen können noch so gut und richtig sein – wenn man diesen Wert von außen nicht rasch erkennen kann, steigt die waste-Gefahr!
Geben Sie Ihren Stakeholdern deshalb stets die Möglichkeit, sich rasch zu orientieren. Ordnen Sie Informationen immer so an, dass Wichtiges zuerst gesehen wird. Erst, wenn sich ein Stakeholder mit den Eckdaten identifizieren kann, besteht die Chance, dass die Inhalte ihren Zweck erfüllen.
Wählen Sie deshalb kurze, aber sprechende Titel. Geben Sie einleitend einen kurzen Hinweis auf Ziel und Kontext des Dokuments. Platzieren Sie Kernaussagen möglichst sichtbar und übersichtlich. Überlassen Sie dagegen Zusatzinfos und Temporäres eher dem zweiten Blick.
Tipp 5: Das persönliche Gespräch geht vor
In dem Moment, in dem dokumentiert wird, ist ein wesentlicher Schritt getan. Nämlich die Entscheidung, dass Sprechen nicht (mehr) das Mittel der Wahl ist. Zu häufig wird diese Entscheidung leider nicht bewusst getroffen, wodurch die Chancen auf Verbesserungen in der Zusammenarbeit vermindert werden.
Aber nichts ist effektiver als das persönliche Gespräch! Direkter Informationsaustausch, sofortiges Feedback, non-verbale Kommunikation. Möglichkeiten, die ein Schriftstück nicht bieten kann.
Streben Sie deshalb stets danach, mehr zu sprechen und weniger zu schreiben. Informationen, die nur von kurzer Relevanz sind oder Verständnis, das einmal geschaffen wurde, muss nicht niedergeschrieben werden.
Seien Sie sich aber auch bewusst, dass man reden können (u.a. co-located?) und wollen muss (u.a. introvertiert?). Nehmen Sie auf jeden Fall Rücksicht auf Ihr Umfeld.
Tipp 6: Nutzen Sie Blackboxing & Perspektivenwechsel
Kennen Sie Situationen, in denen zwei Personen völlig aneinander vorbei sprechen und es nicht merken? Das ist aufgrund unterschiedlicher Wissensstände oft verständlich – trotzdem führt das zu sehr ineffektiver Zusammenarbeit.
Um das zu vermeiden ist es ratsam, gemeinsam besprochene Themen als Blackboxes abzubilden und zu benennen. Eine Blackbox ist ein Begriff, hinter welchem zum einen eine bestimme Bedeutung definiert ist. Zum anderen assoziieren Team-Mitglieder individuelles Wissen dazu.
Durch die Blackbox kann auf Augenhöhe kommuniziert werden. Umständliche Umschreibungen werden vermieden und trotzdem wird spezifisches Wissen bewahrt.
Nutzen Sie die geschlossene (abstrakte) und geöffnete (konkrete) Box auch dazu, absichtlich andere Sichten zu simulieren. Dadurch wird der Gedankenaustausch angeregt und es kommt zu neuen Erkenntnissen.
Tipp 7: Beachten Sie Vorschriften
Beim Bestreben, durch Dokumentieren besser zusammen zu arbeiten, spielen auch Vorgaben, die nicht geändert werden können, eine wichtige Rolle. Normen, Gesetze, Verträge und mehr verlangen Ergebnisse, deren Form und Umfang nicht frei gewählt werden können.
Daher müssen solche Vorgaben und Vereinbarungen bekannt sein und respektiert werden. Gerade in diesen Fällen ist Wert auf hohe Qualität im Sinne der Vorschrift zu legen. Unterschätzen Sie nicht die Auswirkungen von unsachgemäßer Dokumentation.
Um das parallele Existieren vorgegebener und freier Dokumentation zu vereinfachen, nutzen Sie wiederum Labels. Markieren Sie jene Teile, die der Erfüllung einer Norm dienen. So haben Sie auch automatisch ein Inhaltsverzeichnis für die normgerechte Dokumentation erstellt und können diese „auf Knopfdruck“, z.B. für einen Audit, bereitstellen.
Tipp 8: Gestalten Sie jedes Dokument ansprechend
Ob ein Dokument einem Stakeholder nützt, hängt in nicht zu unterschätzendem Maße auch von emotionalen Einflüssen ab. Auch etwas Niedergeschriebenes führt zu User Experience. Nur wenn etwas intuitiv gemocht wird, wird es auch genutzt.
Sorgen Sie deshalb für ansprechendes Dokumenten-Design. Wählen Sie eine Darstellung, bei der Infos durch die natürliche Auffassungsgabe des Menschen direkter transportiert werden können. Meist sind visuelle Eindrücke schneller zu erfassen.
Setzen Sie eher Modelle und Grafiken ein, als textuelle Beschreibungen. Achten Sie auf ein lockeres Schriftbild durch Abstände und Hervorhebungen. Wenn Sie ausformulieren, achten Sie vor allem auf kurze Sätze. Als Faustregel gilt: Nicht mehr als 20 Worte pro Satz.
Tipp 9: Setzen Sie auf Documentation Mapping
Bei der Dokumentenablage gibt es Stolpersteine, die waste verursachen. Nämlich dann, wenn ein Artefakt nicht auffindbar ist. Insel-Dokumente sind nur durch einen direkten Link zugänglich, wodurch die Wiederverwendbarkeit stark beeinträchtigt wird.
Erstellen Sie Ihr gesamtes Dokumenten-Repository deshalb in Form einer Document Map. Verlinken Sie jede Form von Dokument mit einem sinnvollen anderen. Erstellen Sie eine logische Gliederung, durch die vom Groben ins Feine und umgekehrt navigiert werden kann.
Beim Documentation Mapping gibt es keine Einschränkung, welche Dokumenten-Gattungen zur Verlinkung geeignet sind. Der gemeinsame Nenner ist immer der Kundennutzen – egal ob Meeting-Protokoll oder Benutzerdokumentation.
Tipp 10: Nutzen Sie Tools & Automatisierung
Die Frage nach dem richtigen Tool ist eine gleichzeitig sehr zentrale wie auch schwierige. Das „beste“ Tool ist immer abhängig vom Umfeld und somit von den eigenen Anforderungen.
Überlegen Sie, welche Art von Tool Sie benötigen. Definieren Sie Ihre Mindestanforderungen wie Multi-User-Fähigkeit, Security, Workflow-Management und mehr. Evaluieren Sie Kandidaten systematisch.
Nutzen Sie auch Automatisierung, wo es möglich und für Ihren Einsatz sinnvoll ist. Grundsätzlich gilt: Je abstrakter die Beschreibung, desto schwieriger ist es, automatisierte Tool-Unterstützung zu finden.
Nichts desto trotz: Egal ob etablierte Automatisierungs-Lösungen wie Javadoc oder kleine Helferlein wie Plug-Ins zur automatischen Verlinkung, jeder Schritt in Richtung Automatisierung ist (wahrscheinlich) gut.
Expertenwissen aus erster Hand – Fortsetzung folgt...
Für alle Interessierten bietet SEQIS heuer noch weitere Fachvorträge zu aktuellen IT-Themen mit jeweils 10 praxisnahen Tipps und Tricks:
• 21. September 2017: „Kreativität in der IT Analyse“
• 16. November 2017: „Security“
Alle Informationen zu den Vorträgen sowie die Möglichkeit zur kostenlosen Anmeldung befinden sich auf der SEQIS Website unter www.SEQIS.com.
Sinnvolle und richtige Dokumentation ist das Grundgerüst jedes IT-Projekts. Dokumentation dient der effektiveren Zusammenarbeit und der Verfolgung wirtschaftlicher Ziele. Damit Dokumente ihren Zweck erfüllen, müssen schon zu Beginn folgende Überlegungen getroffen werden: Wer ist die Zielgruppe der Dokumentation (Stakeholder)? Wofür soll das Dokument stehen (Nutzen)? Ist das Dokument valide und messbar?
Doch wie viel Dokumentation ist wirklich notwendig? Und wie kann die Zusammenarbeit von Fachseite und IT-Spezialisten bei der Dokumentation erfolgen, obwohl Sprachgebrauch und Werkzeuge gänzlich unterschiedlich sind? Vinzenz Preiss hat dafür 10 praxisnahe Expertentipps parat, die er im Rahmen eines Expertentreffs den zahlreichen Teilnehmern weitergab:
Tipp 1: Jedes Dokument muss messbar den Nutzen einer Zielgruppe erfüllen
Beim Schreiben wird selten ein kritischer Blick auf das Erfolgspotenzial des Dokuments geworfen. Zu schnell öffnet sich ein Editor und es wird darauf losgetippt. Wenn dabei zu viel Aufwand investiert wird, der ohne Gegenwert bleibt, wurde waste produziert. Wenn überhaupt, wird das erst, nachdem der Aufwand schon getrieben wurde, erkannt.
Nehmen Sie sich daher die Zeit und definieren Sie die Berechtigung für die Existenz des Dokuments bevor Sie mit der Ausarbeitung beginnen: Definieren Sie die Zielgruppe Ihres Dokuments. Überlegen Sie sich, welches Problem dieser Zielgruppe das Dokument löst. Ohne Empfänger oder dessen Nutzen genau zu kennen gibt es keinen Grund, Arbeit zu investieren. Verifizieren Sie Ihre Annahmen durch Messungen. Nur so können Sie leere Kilometer vermeiden (waste) und Wertvolles absichern.
Tipp 2: Starten Sie Ihr Dokument früh, detaillieren Sie es jedoch spät
Der Product Life Cycle (PLC) umfasst zahlreiche Phasen zur Erstellung und zum Betrieb eines Software-Produkts. Entlang dieses Prozesses reift das Produkt und verändert sich, bis es schließlich seinen definierten Zweck erfüllen kann. In diesen Phasen gibt es auch zahlreiche Dokumente, die auf unterschiedliche Weise nützlich sind.
Genauso muss auch ein Dokument erst Phasen der Reifung durchlaufen, ehe es von Nutzen ist. Machen Sie sich bewusst, welchen Lauf der Document Life Cycle (DLC) nimmt. Synchronisieren Sie den DLC mit relevanten Meilensteinen des PLC, um Informationen rechtzeitig zu liefern. Auch ein Dokument erfordert Zeit und Arbeit zum Entstehen.
Unterstützen Sie diesen Prozess durch frühe Stichworte und validieren Sie inhaltliche Eckpunkte. Formulieren Sie aber erst möglichst spät aus. Je später Sie Ihre Beschreibung in die finale Form bringen, desto geringer ist die Gefahr von unerwünschtem Änderungsaufwand.
Tipp 3: Dokumentieren Sie wiederverwendbar
Bei der Beschreibung – speziell in Textform – wird häufig ein Ablauf skizziert. Weil der gewünschte Endzustand fokussiert wird, wird dieser direkt beschrieben. Dahinterliegende Implementierungen sind jedoch meist objektorientiert aufgebaut. Sie sind wiederverwendbar und können mehrere Szenarien ohne erneute Implementierung abbilden.
Auch Dokumentation kann objektorientiert gestaltet werden. Wenn Sie Generisches von Szenarien trennen, haben Sie die Möglichkeit zur Wiederverwendung.
Durch Labels lassen sich generische Beschreibungen mit einem Kontext markieren. Bei Aufruf des Labels wird automatisch eine Dokumentation für diesen einen Kontext erstellt, ohne dass für jedes Stichwort eigene Dokumente existieren. Es gibt nur ein Original. Dadurch entfällt die Gefahr von Fehlern durch Redundanz und Beschreibungsanomalien.
Tipp 4: Übersichtlichkeit zählt vor Details
Um Menschen Information zugänglich zu machen, muss diese Information erst einmal gefunden und als relevant erkannt werden. Inhaltliche Abhandlungen können noch so gut und richtig sein – wenn man diesen Wert von außen nicht rasch erkennen kann, steigt die waste-Gefahr!
Geben Sie Ihren Stakeholdern deshalb stets die Möglichkeit, sich rasch zu orientieren. Ordnen Sie Informationen immer so an, dass Wichtiges zuerst gesehen wird. Erst, wenn sich ein Stakeholder mit den Eckdaten identifizieren kann, besteht die Chance, dass die Inhalte ihren Zweck erfüllen.
Wählen Sie deshalb kurze, aber sprechende Titel. Geben Sie einleitend einen kurzen Hinweis auf Ziel und Kontext des Dokuments. Platzieren Sie Kernaussagen möglichst sichtbar und übersichtlich. Überlassen Sie dagegen Zusatzinfos und Temporäres eher dem zweiten Blick.
Tipp 5: Das persönliche Gespräch geht vor
In dem Moment, in dem dokumentiert wird, ist ein wesentlicher Schritt getan. Nämlich die Entscheidung, dass Sprechen nicht (mehr) das Mittel der Wahl ist. Zu häufig wird diese Entscheidung leider nicht bewusst getroffen, wodurch die Chancen auf Verbesserungen in der Zusammenarbeit vermindert werden.
Aber nichts ist effektiver als das persönliche Gespräch! Direkter Informationsaustausch, sofortiges Feedback, non-verbale Kommunikation. Möglichkeiten, die ein Schriftstück nicht bieten kann.
Streben Sie deshalb stets danach, mehr zu sprechen und weniger zu schreiben. Informationen, die nur von kurzer Relevanz sind oder Verständnis, das einmal geschaffen wurde, muss nicht niedergeschrieben werden.
Seien Sie sich aber auch bewusst, dass man reden können (u.a. co-located?) und wollen muss (u.a. introvertiert?). Nehmen Sie auf jeden Fall Rücksicht auf Ihr Umfeld.
Tipp 6: Nutzen Sie Blackboxing & Perspektivenwechsel
Kennen Sie Situationen, in denen zwei Personen völlig aneinander vorbei sprechen und es nicht merken? Das ist aufgrund unterschiedlicher Wissensstände oft verständlich – trotzdem führt das zu sehr ineffektiver Zusammenarbeit.
Um das zu vermeiden ist es ratsam, gemeinsam besprochene Themen als Blackboxes abzubilden und zu benennen. Eine Blackbox ist ein Begriff, hinter welchem zum einen eine bestimme Bedeutung definiert ist. Zum anderen assoziieren Team-Mitglieder individuelles Wissen dazu.
Durch die Blackbox kann auf Augenhöhe kommuniziert werden. Umständliche Umschreibungen werden vermieden und trotzdem wird spezifisches Wissen bewahrt.
Nutzen Sie die geschlossene (abstrakte) und geöffnete (konkrete) Box auch dazu, absichtlich andere Sichten zu simulieren. Dadurch wird der Gedankenaustausch angeregt und es kommt zu neuen Erkenntnissen.
Tipp 7: Beachten Sie Vorschriften
Beim Bestreben, durch Dokumentieren besser zusammen zu arbeiten, spielen auch Vorgaben, die nicht geändert werden können, eine wichtige Rolle. Normen, Gesetze, Verträge und mehr verlangen Ergebnisse, deren Form und Umfang nicht frei gewählt werden können.
Daher müssen solche Vorgaben und Vereinbarungen bekannt sein und respektiert werden. Gerade in diesen Fällen ist Wert auf hohe Qualität im Sinne der Vorschrift zu legen. Unterschätzen Sie nicht die Auswirkungen von unsachgemäßer Dokumentation.
Um das parallele Existieren vorgegebener und freier Dokumentation zu vereinfachen, nutzen Sie wiederum Labels. Markieren Sie jene Teile, die der Erfüllung einer Norm dienen. So haben Sie auch automatisch ein Inhaltsverzeichnis für die normgerechte Dokumentation erstellt und können diese „auf Knopfdruck“, z.B. für einen Audit, bereitstellen.
Tipp 8: Gestalten Sie jedes Dokument ansprechend
Ob ein Dokument einem Stakeholder nützt, hängt in nicht zu unterschätzendem Maße auch von emotionalen Einflüssen ab. Auch etwas Niedergeschriebenes führt zu User Experience. Nur wenn etwas intuitiv gemocht wird, wird es auch genutzt.
Sorgen Sie deshalb für ansprechendes Dokumenten-Design. Wählen Sie eine Darstellung, bei der Infos durch die natürliche Auffassungsgabe des Menschen direkter transportiert werden können. Meist sind visuelle Eindrücke schneller zu erfassen.
Setzen Sie eher Modelle und Grafiken ein, als textuelle Beschreibungen. Achten Sie auf ein lockeres Schriftbild durch Abstände und Hervorhebungen. Wenn Sie ausformulieren, achten Sie vor allem auf kurze Sätze. Als Faustregel gilt: Nicht mehr als 20 Worte pro Satz.
Tipp 9: Setzen Sie auf Documentation Mapping
Bei der Dokumentenablage gibt es Stolpersteine, die waste verursachen. Nämlich dann, wenn ein Artefakt nicht auffindbar ist. Insel-Dokumente sind nur durch einen direkten Link zugänglich, wodurch die Wiederverwendbarkeit stark beeinträchtigt wird.
Erstellen Sie Ihr gesamtes Dokumenten-Repository deshalb in Form einer Document Map. Verlinken Sie jede Form von Dokument mit einem sinnvollen anderen. Erstellen Sie eine logische Gliederung, durch die vom Groben ins Feine und umgekehrt navigiert werden kann.
Beim Documentation Mapping gibt es keine Einschränkung, welche Dokumenten-Gattungen zur Verlinkung geeignet sind. Der gemeinsame Nenner ist immer der Kundennutzen – egal ob Meeting-Protokoll oder Benutzerdokumentation.
Tipp 10: Nutzen Sie Tools & Automatisierung
Die Frage nach dem richtigen Tool ist eine gleichzeitig sehr zentrale wie auch schwierige. Das „beste“ Tool ist immer abhängig vom Umfeld und somit von den eigenen Anforderungen.
Überlegen Sie, welche Art von Tool Sie benötigen. Definieren Sie Ihre Mindestanforderungen wie Multi-User-Fähigkeit, Security, Workflow-Management und mehr. Evaluieren Sie Kandidaten systematisch.
Nutzen Sie auch Automatisierung, wo es möglich und für Ihren Einsatz sinnvoll ist. Grundsätzlich gilt: Je abstrakter die Beschreibung, desto schwieriger ist es, automatisierte Tool-Unterstützung zu finden.
Nichts desto trotz: Egal ob etablierte Automatisierungs-Lösungen wie Javadoc oder kleine Helferlein wie Plug-Ins zur automatischen Verlinkung, jeder Schritt in Richtung Automatisierung ist (wahrscheinlich) gut.
Expertenwissen aus erster Hand – Fortsetzung folgt...
Für alle Interessierten bietet SEQIS heuer noch weitere Fachvorträge zu aktuellen IT-Themen mit jeweils 10 praxisnahen Tipps und Tricks:
• 21. September 2017: „Kreativität in der IT Analyse“
• 16. November 2017: „Security“
Alle Informationen zu den Vorträgen sowie die Möglichkeit zur kostenlosen Anmeldung befinden sich auf der SEQIS Website unter www.SEQIS.com.
