The power of pairing

Paar-Dokumentation bei einem Übergabe-Projekt

Christine Hennig, Wolfram Eifler

  1. September 2020

Einführung

Pair documentation sollte doch keine neue Idee gegenüber Pair programming sein – dachten wir.
Die Internet-Recherche zum Thema “pair documentation” lieferte ein mageres Ergebnis.

  • Einen Praxisbericht über 50 Stunden gemeinsame Dokumentation in der Open Source Community ([1]).
  • Eine empirische Studie über die Erstellung einer SRS (software/system requirements specification) als Einzelperson versus als Team ([2])

Hier unsere eigenen Erfahrungen mit dem Thema.

Anlaß war die Arbeits-Übergabe eines Mitarbeiters bei Verlassen des Unternehmens und die Sicherung des erarbeiteten Wissensstandes. Bestandteil der Übergabe war ein Prototyp bzw. Referenz-Implementierung in einem fortgeschrittenen Stadium. Er umfasste mehrere umfangreiche Technologie-Stacks.

Zur Verfügung stand ein Dokumentations-System im Intranet mit einer MediaWiki-Installation. Alle Dokumente sind als einzelne oder Verbund mehrerer Wiki-Seiten im System abgelegt.
Jedes Thema befindet sich in einem definierten Zustand, der von “Inkubator” bis “Freigabe” über mehrere Review-Zyklen läuft. Die Arbeiten fanden während der Corona-Pandemie im Homeoffice statt.

Beschrieben ist zum einen unser initialer Plan und zum anderen unsere Erfahrungen.

Hier der Plan

Ausgangslage:

  • Ein Mitarbeiter verlässt die Firma.
  • Mit den verbleibenden Arbeitsstunden ist eine möglichst vollständige Übergabe zu bewerkstelligen.

Lösungsansatz:

  • Pingpong zwischen Mitarbeiter (Contentproduktion / MA) und Redakteurin (Qualitätssicherung / QS).
  • Der redaktionelle Ablauf ist frei von Loops. So wird ein unnötiges Abgleiten in Details vermieden.
  • Die einzelnen Arbeitsschritte sind mit einem geschätzten Zeitkontingent hinterlegt.

Planung:

  • Die dokumentarisch zu bearbeitenden Themen werden im Vorfeld aufgelistet.
  • Jedes Thema durchläuft den nachfolgend genannten Arbeitsfluss.
  • Zu Beginn ist die Anzahl der zu bearbeitenden Themen mit der noch zur Verfügung stehenden Zeit abzustimmen.
  • Die verfügbare Zeit wird zu Beginn realistisch auf die Themen verteilt. Die Freiheitsgrade sind Detailtiefe, Markierung als optional und ggf. Streichung des jeweiligen Themas.

Arbeitsfluss je Thema:

NummerStundenWerZustandWas
1.01QSInkubatorSeite im System anlegen, (ggf. vorläufigen) Titel vergeben
1.11MASammelnMaterial sammeln
1.21MAOrdnenBezug zu existierender Dokumentation herstellen
1.33MAOrdnenStrukturieren/Gliedern
2.01QSPreviewStruktur auf Plausibilität kontrollieren
3.010MAAngefangenschreiben, schreiben schreiben
4.05QSReview1Inhaltlich, strukturell, Korrektheit, Konsistenz, Aktualität
5.03QS + MAHands-On Doku gegen techn. System halten, Lücken aufspüren usw.
6.04MAErgänzen1Vervollständigen, ggf. Struktur verbessern
7.03QSReview2Inhalt, Struktur
8.03MAErgänzen2Vervollständigen, ggf. Struktur verbessern
9.02QSReview3Rechtschreibung, Grammatik, tote Links
10.01QSFreigabeFertig

Ergebnis:

  • Alle geplanten Themen sind grundsätzlich bearbeitet.
  • Kein Thema ist wegen Detailversessenheit untergegangen.
  • Es ergibt sich eine Dokumentation, die Nachfolgern einen sinnvollen Ansatzpunkt liefert, um am Thema weiterzuarbeiten.

Dort die Realität

Wie immer kommt es (ein wenig) anders. Zu Beginn implementierten wir einen Backup-Mechanismus zur Sicherung der Doku-Zwischenstände.

Nach unserer Planung erfordert Punkt 3 (Schreiben, schreiben, schreiben) knapp die Hälfte der Zeit. Das entsprach der Realität.

Ab Punkt 5 (Hands-On) arbeiteten wir dann fast nur noch gemeinsam an der Doku. Die geplante Zeit wurde dazu in etwa wie erwartet benötigt, jedoch ergab sich häufig parallele Arbeit im selben Ablaufpunkt an mehreren miteinander verknüpften Themen. Außerdem justierten wir regelmäßig die verbleibenden Arbeiten nach Priorität und Zeitkontingent, teilweise auch in ihrer Struktur.

Die Reviewerin / QS-Verantwortliche hatte natürlich viele Fragen, das ist schließlich ihr Job. Die Fragen führten dazu, dass die Doku viel verständlicher und besser strukturiert wurde. Jede Rückfrage wurde genutzt, um Form und Struktur der Beschreibung zu optimieren. Die Zielvorstellung dabei war, den hinterfragten Sachverhalt noch klarer zu beschreiben.

Wir arbeiteten die Änderungen abwechselnd ein. Die Hands-On Sitzungen wurden mal von der QS, mal vom Mitarbeiter durchgeführt. Die zweite Person passte jeweils auf, dass alles richtig getippt wird und bei jedem Kommandobeispiel klar ist, was damit bezweckt wird und ob dies auch angemessen aus der Doku hervorgeht.

Dabei ging es dann direkt an den Prototyp, ohne ihn kaputtzumachen. Natürlich hatten wir ein Backup für den Notfall.

Aufkommende weitere Themen, Anmerkungen und Wünsche, die den aktuellen Rahmen sprengten, wurden fortlaufend an das Ende einer ToDo Liste angehängt.
Diese Abgrenzung entlastete den Mitarbeiter von Unterbrechungen beim Schreiben, ohne dass Thematiken verlorengingen. Die Liste wurde wöchentlich priorisiert (must, should, could, won’t [3]) sowie mit dem erreichten Fortschritt und Zeitplan abgeglichen.

Gemeinsam kamen wir in gute Energie und der Flow ([4]) ließ nicht lange auf sich warten. Die Zeit verging wie im Flug.
So zogen sich unsere Video-Meetings meist so lange hin, bis eine Person von uns beiden Hunger bekam.

Alles in allem hatten wir viel Spass und ein gutes Gewissen, den Job unter den gegebenen Bedingungen so gut abgeliefert zu haben.

Persönliches Fazit

Paar-Dokumentation

  • ist produktiv
  • verbessert die Qualität der Dokumentation
  • sorgt für Wissens-Weitergabe
  • macht Spaß
  • funktioniert auch im Homeoffice

Gemeinsame Planung ist hilfreich, um den Fokus zu halten und in jeder Phase Wichtiges von Unwichtigem zu unterscheiden.

Referenzen

Tagged with: , ,
Posted in IT allgemein, Wissensmanagement

Was clean code und effiziente Wissens-Strukturierung gemeinsam haben

Wenn ich ein komplexes Thema inhaltlich beschreibe, stellt es mich vor vielfältige Herausforderungen.

Eine übliche Art der Bearbeitung ist die Aufteilung des Inhalts in sog. Topics, die spezielle Aspekte dieses Inhalts beschreiben.
Diese Topics können mit Assoziationen, also Beziehungen untereinander, versehen werden.

Eine Topic Map dient dazu, den Überblick über alle Topics zu erhalten. Sie ist die “Landkarte”, auf der alle Topics und deren Beziehungen verzeichnet sind.
In ihr kann navigiert werden und auch auf die einzelnen Topics über einen Index zugegriffen.

Hierbei stellt sich die Frage, wie umfangreich die einzelnen Topics erstellt werden und welche Aspekte in welchem Topic dokumentiert werden.

Dabei helfen mir die Regeln der Clean Code Developer [1].
Was für Entwickelnde gut ist, kann für Dokumentierende nicht falsch sein.
Im Orangenen Grad sollen folgende Prinzipien eingehalten werden, die ich gleich auf Topics abbilde:

  • Single Level of Abstraction: Die Einhaltung eines Abstraktionsniveaus fördert die Lesbarkeit.
  • Single Responsibility Principle: Fokus erleichtert das Verständnis. Ein Topic mit genau einer Aufgabe ist verständlicher als ein Gemischtwarenladen.
  • Separation of Concerns: Wenn ein Topic keine klare Aufgabe hat, ist es schwer ihn zu verstehen und ggf. zu korrigieren oder zu erweitern.
  • (Source Code) Konventionen: Topics werden häufiger gelesen und recherchiert als geschrieben. Daher sind (Dokumentations-)Konventionen wichtig, die ein schnelles Lesen und Erfassen des Topics unterstützen.

Die Herausforderungen guter Software-Entwicklung und guter technischer Dokumentation ähneln sich also verblüffend.

[1] https://clean-code-developer.de/die-grade/orangener-grad/

Tagged with: , , ,
Posted in Wissensmanagement

Informationsqualität

Diesmal als MindMap:

Informationsqualität

Aus dem Klassiker
“Developing Quality Technical Information”
von Hargis, Carey, Hernandez, Hughes, Longo, Rouiller, Wilder

Download in voller Auflösung:

Tagged with: ,
Posted in Wissensmanagement

Einführung eines maßgeschneiderten Wissensmanagements bei einem IT-Dienstleister

Vortragsfolien

Einführung Wissensmanagement

Tagged with: , ,
Posted in GI, Wissensmanagement

Frauen in der Tech-Szene

Dank meinem Engagement in der Gesellschaft für Informatik wurde ich für eine Podiumsdiskussion angefragt. Es ging um die Frage, warum der Frauenanteil in der IT und den technischen Berufen immer noch so gering ist.

Hier der Link zum Beitrag:

https://www.wissenschaftsjahr.de/2018/neues-aus-den-arbeitswelten/alle-aktuellen-meldungen/oktober-2018/frauen-in-der-tech-szene-wird-die-ausnahme-je-zum-alltag/

Tagged with: , , , , , , ,
Posted in GI, IT allgemein

Die 4 Arten von technischer Dokumentation am Beispiel eines Zitronenkuchens

Am Wochenende war ich in Prag. Die WriteTheDocs Community hatte ihre EU Konferenz und ich, neu in Tech Docs, war zum ersten Mal dabei:

http://www.writethedocs.org/conf/eu/2017/

Den Eröffungs-Vortrag hielt Daniele Procida mit dem Titel
“The four kinds of documentation, and why you need to understand what they are”

Und das sind sie, die vier Arten der Dokumentation:

  • klassifiziert mit ihrem Fokus
  • gruppiert nach
    • lernen oder tun
    • Theorie oder Praxis
TUTORIAL learning studying practice
HOW-TO problem-solving doing practice
EXPLANATION understanding studying theory
REFERENCE information doing theory

Ich habe nun auch den Unterschied zwischen einem Tutorial und einem How-To verstanden, die ich übrigens beide als “Anleitung” übersetzt bekomme.

Das Tutorial lehrt, wie es prinzipiell geht. Dies gern an einem Beispiel. Es geht aber um das Lernen. “Wir lernen einen Kuchen backen.”

Das How-To erklärt ein konkretes Thema. Das Thema ist eben gerade kein Beispiel, sondern das, worum es geht. Sie setzt ein gewisses Grundverständnis voraus, zum Beispiel wie man einen Kuchen backt und wie man ein Rezept liest. “Wir backen einen Zitronenkuchen.” wird dann das Zitronenkuchenrezept.

In der Referenz kann ich nachschlagen, welche Backeigenschaften das Mehl hat und was eine Kastenform ist.

Eine Erklärung kann die Vor- und Nachteile des Genusses eines Stück Zitronenkuchens für die menschliche Ernährung darstellen.

Tagged with:
Posted in Wissensmanagement

Ein Bild sagt mehr als tausend Worte

ExperienceBase

Die Idee für diese Grafik entstammt dem Muster Experienced Expert
aus der Masterarbeit von Xiaoxuan Ge vom 08. April 2008
“FLOW Patterns: Beschreibung und Diskussion von Informationsflussmustern in der Softwareentwicklung”:

Click to access Xiaoxuan_Ge-FLOW-Patterns-Katalog.pdf

Posted in IT allgemein, Wissensmanagement

Architekturdokumentation mit der arc42 Methode

Zum dritten Mal wende ich das template von Starke und Hruschka an.
Liebe Leute, Ihr habt mir (mal wieder) den Arsch gerettet!
Heute ist es an der Zeit, mich dafür mit diesem Beitrag zu bedanken.

http://www.arc42.de/
Unter dieser Webseite bieten die Autoren seit einigen Jahren ihre gesammelten Erfahrungen im IT Consulting mit dem Schwerpunkt Software-Architektur an.

42 ist die Antwort und der Name ist Programm.
Sie haben ein neues Projekt und wollen es verstehen?
Sie kommen neu in ein altes Projekt und wollen es verstehen?
Es ist sogar ein IT Projekt? Eine Software?
42 ist die Antwort. Arc42 bietet u.a. ein template zur Architekturdokumentation.
Arbeiten Sie es durch und Sie kommen an jeder Schmuddelecke Ihres Projektes vorbei. Danach kennen Sie Ihr Projekt besser als Ihre Westentasche.

Ein Projekt mit Arc42 durchzuarbeiten ist nach meiner Erfahrung durchaus aufwändig und an einigen Stellen herausfordernd. Ich benutze es als Leitfaden.
Natürlich wissen Sie, dass Sie alle Stakeholder Ihres Projektes kennen sollten.
Versuchen Sie mal, diese aufzuschreiben.
Natürlich wissen Sie, dass Qualitätskritieren Bestandteil der Anforderungen sind.
Versuchen Sie mal, diese aufzuschreiben. Sie müssen dazu vermutlich mehrmals mit Ihren Stakeholdern iterieren. Gut, dass Sie die ja schon kennen.
Natürlich wissen Sie, dass Sie sich mit den Risiken Ihres Projekts beschäftigen müssen.
Machen Sie sich die Mühe, die Risiken zu beschreiben und zu bewerten. Und vergessen Sie das Iterieren mit den Stakeholdern nicht.
Arc42 führt Sie durch alle diese Bereiche, unterstützende Texte helfen Ihnen, die Inhalte zu bestimmen und festzuzurren.
Selbst ein Kapitel über Entwurfsentscheidungen ist enthalten, so läßt sich später jederzeit nachvollziehen, warum sich für diese und gegen jene Lösung entschieden wurde.
Quasi von selbst entsteht dabei die Dokumentation Ihrer Software-Architektur mit allem, was Sie in diesem Umfeld wissen müssen.

Nach meiner Erfahrung läßt sich die Arc42 Methode auch für Nicht-Software-Projekte durchführen. Vermutlich sogar für Projekte aus beliebigen (technischen) Bereichen, wenn Sie nicht relevante Kapitel weglassen oder entsprechend modifizieren.

So habe ich das Projekt MobileCoDaC, ein IT Infrastrukturprojekt, mit Arc42 gezähmt.

Ebenfalls erfolgreich habe ich Arc42 für die Software-Architekturdokumentation meines Software-Entwicklungs-Projektes ArchiveDB verwendet.

Diesmal habe ich mit der Arc42 Methode die Architektur einer IT Wissensbasis bearbeitet und jetzt weiss ich ebenso wie meine Stakeholder sehr genau, was das System leisten soll und wie es aufgebaut wird.

Tagged with: ,
Posted in Wissensmanagement

Modelle über den Wissenserwerb

Um Meisterschaft zu erreichen, benötigt der Mensch 10000 Stunden Beschäftigung mit einem Thema. Aber nicht jeder erreicht diese Meisterschaft. Und auch einmal erreichte Meisterschaft in einem Gebiet kann wieder verloren gehen, wenn es zu selten praktiziert wird.

Um herauszufinden, wie Wissensmanagment gelingen kann, habe ich mich mit diversen Modellen des Wissenserwerbs beschäftigt. Modelle sind nur Modelle. Eine Person bezüglich ihres Wissens zu einem Thema in ein Modell einzusortieren, ist immer eine Vereinfachung.

Nahezu allen Modellen ist eine 4- oder 5stufige Pyramide gemeinsam. Daher habe ich diese in einer einzigen Tabelle aufeinander abgebildet und mit weiteren Bemerkungen versehen. Die Tabelle ist als Pyramide zu lesen: die höheren Zeilen bauen immer auf den darunterliegenden Zeilen auf.

Niveau [1] DIKW Modell [2] Dreyfus Modell [3] Komplexität [4] / Effizienz [5] / W-Frage Braucht:
Unbewusste Kompetenz Wisdom / Können Experte / Guru Komplex Intuition
Bewusste Kompetenz Understanding / Verstehen Erfahren / Gewandt / Versiert Kompliziert / Effektiv / Warum Erklärungen
Bewusste Inkompetenz Knowledge / Wissen Fachkraft / Kompetente Effizient / Wie Anleitungen / Checklisten
Unbewusste Inkompetenz Information (fortgeschrittene) Anfänger / Neuling Einfach / Was Regeln

Literatur

[1] https://de.wikipedia.org/wiki/Kompetenzstufenentwicklung
[2] https://en.wikipedia.org/wiki/DIKW_pyramid
[3] https://en.wikipedia.org/wiki/Dreyfus_model_of_skill_acquisition
[4] https://de.wikipedia.org/wiki/Komplexität und https://de.wiktionary.org/wiki/kompliziert
[5] https://de.wikipedia.org/wiki/Effektivität#Der_Unterschied_zwischen_Effektivität_und_Effizienz

Tagged with: ,
Posted in Wissensmanagement

Zukunft durch Aufstieg: Cross-Mentoring

Jeder Frau, die in Mecklenburg-Vorpommern lebt und eine Führungstätigkeit in der Wirtschaft anstrebt, sei das Cross-Mentoring Programm des Landes Zukunft durch Aufstieg empfohlen.

http://www.zukunft-durch-aufstieg.de

Für mich als Mentorin wieder eine spannende Möglichkeit, über meinen fachlichen Tellerrand hinauszublicken. Sowohl meine Mentee stammt aus einer anderen Branche als ich als auch die anderen Mentorinnen und Mentoren. Cross bedeutet also branchenübergreifend und firmenübergreifend.

Geht denn das, kann ich eine Mentee betreuen, die keine IT-Frau ist? Ja, es geht. Die Themen sind universell und die Lösungen sind individuell. Und auch das ist Wissens-Management. Die Weitergabe von Erfahrungswissen.

Im Kreis der Mentor_innen haben wir reflektiert, wie das Programm bekannter gemacht werden kann. Dies ist mein Beitrag dazu.

Tagged with:
Posted in Wissensmanagement