QM meets CI - Entwicklerfreundliche Prozessdokumentation

Marie Mann | | talk

"Hey Marie, wie beantrage ich nochmal meinen Urlaub?" Da ich bei Pengutronix in der Verwaltung und im Projektmanagement arbeite, kenne ich diese Art Fragen nur zu gut, und seit ich unsere Prozesse aufschreibe, kann ich (endlich) auch einmal mit "RTFM" antworten. Prozesse sind Arbeitsabläufe, die immer wieder durchgeführt werden müssen, manchmal in einem festen Intervall, manchmal nach Bedarf.

Als 2018 die Prozessdokumentation bei Pengutronix von Grund auf überarbeitet wurde, stand vor allem die Frage im Raum, wie die MitarbeiterInnen an der Entstehung der Prozesse beteiligt werden können. Für die Dokumentation wurden Abläufe und Tools gewählt, die bereits bei der Mehrheit der MitarbeiterInnen etabliert waren.

Dieser Beitrag stellt die gewählten Werkzeuge vor, zeigt das Vorgehen und erläutert ergänzend zu dem Vortrag exemplarisch den Aufbau einer Prozessbeschreibung.

Warum Prozesse aufschreiben?

Sobald ein Unternehmen groß genug ist, dass nicht mehr alle MitarbeiterInnen in einem Raum sitzen und mitbekommen, an welchen Aufgaben gerade wie gearbeitet wird, entsteht die Notwendigkeit, genau diese Abläufe aufzuschreiben. Die Prozessdokumentation ermöglicht, das Wissen um die Abläufe festzuhalten und Regeln aufzustellen.

Die Regeln werden zwar von der Geschäftsführung vorgegeben, sind aber für alle MitarbeiterInnen einseh- und damit auch einforderbar. Dies ermöglicht eine faire Behandlung aller MitarbeiterInnen.

Wie können MitarbeiterInnen mitgenommen werden?

Das Aufschreiben der Prozesse ist kein Selbstzweck, sondern dient dazu, dass MitarbeiterInnen nachlesen können, wie zum Beispiel der Urlaub beantragt wird.

Oftmals sind die ProzessnutzerInnen die inhaltlichen Experten, da sie den Prozess jeden Tag befolgen und damit leben. Sie wissen am besten, wie ein Ablauf optimiert werden kann. Allein dieser Umstand sollte Grund genug sein, die ProzessnutzerInnen in die Gestaltung der Prozesse mit einzubeziehen:

  • Die Prozesse können durch die NutzerInnen verbessert werden und
  • die Prozesse werden viel bereitwilliger befolgt, wenn sie den NutzerInnen sinnvoll erscheinen.

Der Einstieg in die Softwareentwicklung wird häufig mit einem Kochrezept verglichen. Man könnte ein Kochbuch auch als Prozessdokumentation bezeichnen: Ein Prozess, wie z.B. das Kochen, hat einen Auslöser (Hunger) oder Einstiegspunkt und beschreibt eine Reihe von Handlungsanweisungen.

Wenn die Prozessdokumentation der Quellcode ist, mit dem das Unternehmen läuft, warum nicht die Werkzeuge aus der Softwareentwicklung nutzen, um die Prozessdokumentation zu schreiben?

Bei Pengutronix wurde der Gedankengang ernst genommen, und die Prozessbeschreibungen werden in Form eines Prozesshandbuchs mit den Mitteln der Softwareentwicklung gestaltet.

Für die Umsetzung gab es folgende Anforderungen an die Prozesse und deren Darstellung:

  • Die Prozesse sollen einfach zugänglich sein,
  • die MitarbeiterInnen sollen eine Möglichkeit zur Mitarbeit haben und bei der Gestaltung der Prozesse beteiligt werden,
  • die Prozesse unterliegen (daher) einem Freigabeprozess durch die Geschäftsführung,
  • die Prozesse sollen regelmäßig auf ihre Aktualität geprüft werden.

Werkzeuge und Workflows

Um die Anforderungen zu erfüllen und das Prozesshandbuch als "Softwareprojekt" umzusetzen, werden sowohl Workflow als auch Tooling, die bereits im Unternehmen etabliert sind, genutzt. Beides soll im Folgenden kurz betrachtet werden. Die Beschreibung wird dabei auf die wesentlichen Merkmale reduziert, die notwendig für die Gestaltung der Prozessdokumentation sind.

Linux-Kernel-Workflow

Einer der wichtigsten und am weitesten verbreiteten Workflows bei Pengutronix ist der, mit dem der Linux-Kernel entwickelt wird.

Der Linux-Kernel ist in verschiedene Subsysteme aufgeteilt, die in etwa mit einzelnen Abteilungen eines Unternehmens vergleichbar sind. Je nach Komplexität kann es weitere Subsysteme geben. Mögliche Änderungen an dem Linux-Kernel (Bugfixes, neue Treiber, Verbesserungen an der Code-Qualität) werden zunächst innerhalb des Subsystems diskutiert. Für jedes Subsystem (dieses ist mit einer mittleren Managementebene vergleichbar) ist ein Maintainer verantwortlich, der Tests durchführt und prüft, ob die Qualitätsstandards eingehalten sind. Wenn alles in Ordnung ist, fließen die Änderungen aller Subsysteme in die nächste Version des Linux-Kernels ein. Dieser wird von Linus Torvalds (dem Erstautor und Maintainer von Linux) persönlich released.

Den beschriebenen Workflow haben wir für die Arbeit am Prozesshandbuch adaptiert: Änderungen an der Prozessdokumentation werden mit den jeweiligen ProzessnutzerInnen diskutiert und anschließend an die Geschäftsführung zur Freigabe gegeben. Derzeit ist das Pengutronix-Prozesshandbuch-Projekt noch klein genug, so dass auf das mittlere Management verzichtet werden kann.

Versionskontrolle

Um diesen Workflow realisieren zu können, werden die Prozesse als strukturierte Textdateien geschrieben, die versionskontrolliert verwaltet werden. Der Release-Branch der Versionsverwaltung ist nur für die Geschäftsführung schreibbar, so dass über ein neues Release des Prozesshandbuchs auch gleichzeitig die Freigabe sichergestellt ist.

Der Vorteil von Dateien, die als reStructuredText (.rst) oder Markdown (.md) geschrieben werden im Gegensatz zu nicht-textbasierten Formaten wie .docx oder .odf, ist, dass die inhaltliche Änderung zusammen mit einem Zeitstempel und den Autoren in einer Versionsverwaltung einfach verfolgt werden kann. Zudem ermöglicht eine Versionsverwaltung neben der reinen Änderungsverfolgung auch Beschreibungstexte, in denen festgehalten werden kann, warum eine Änderung erfolgt und welche Entscheidungen zu der Prozessänderung geführt haben.

Web-Darstellung

So groß der Charme von Textdateien aus Sicht der Prozessschreibenden auch ist, für die Prozessnutzenden kann die Benutzerfreundlichkeit verbessert werden. Daher wird bei Pengutronix das quelloffene Software-Dokumentationswerkzeug Sphinx eingesetzt, um eine Webansicht zu generieren. In dieser können die Prozesse sowohl direkt verlinkt werden als auch Formulare, die zu einem Prozess gehören, als Download bereitgestellt werden.

Build-Server

Mit Hilfe eines Build-Servers wird das aktuelle Release der Prozessdokumentation gebaut und als Webansicht zur Verfügung gestellt. Gleichzeitig ermöglicht der Build-Server die Nutzung von automatisierten Tests.

Bei Pengutronix wird beim Bauen durch den Build-Server unter anderem geprüft, ob das Datum, an dem das nächste Prozessreview fällig wäre, überschritten wurde. Sofern dieser Fall eintritt, werden Erinnerungs-E-Mails verschickt, so dass der Prozess zeitnah auf seine Aktualität hin überprüft werden kann.

Das Setup wurde hier nur schematisch beschrieben, da es nicht um konkrete Produkte, sondern deren Einsatz zur Prozessdokumentation im Fokus steht. Wichtig ist, dass eine Versionsverwaltung zur Änderungsverfolgung und ein Buildserver für das "Continuous Testing" und "Continuous Deployment" verwendet werden.

Struktur einer Prozessbeschreibung

Damit das Setup im vollen Umfang genutzt werden kann, ist es entscheidend, dass im Vorfeld eine Struktur für das Handbuch und den Aufbau eines Prozesses festgelegt wird. Ein gutes Beispiel für die Gliederung der Prozesse und, wie so ein Handbuch gestaltet werden kann, ist das "Company Handbook" von GitLab Inc..

Um etwas in die Praxis zu gehen, wird Ausschnittsweise die Struktur eines Prozesses in der Prozessdokumentation von Pengutronix beschrieben sowie exemplarisch ein Test vorgestellt.

Ein Prozess besteht aus drei Abschnitten: Der erste Abschnitt ist eine Tabelle, in der Metadaten erfasst werden. Wann wurde der Prozess zuletzt aktualisiert? Wann ist das nächste Review fällig? Gibt es einen Vorgänger-Prozess? Welcher Prozess schließt sich an den aktuellen Prozess an? Gibt es Formulare zum Download?

Der zweite Abschnitt enthält die eigentliche Prozessbeschreibung. Für diese ist keine feste Form vorgegeben. Damit der Prozess gut lesbar ist, werden weitere Strukturierungselemente, wie Infoboxen oder Aufzählungen, verwendet.

Der dritte Abschnitt ist für allgemeine Informationen reserviert, die an die Qualitätskriterien der ISO 9001 angelehnt sind. Dabei sollen unter anderem folgende Fragen beantwortet werden: Wer sind die ProzessnutzerInnen und -eigentümerInnen? Wann wird der Prozess aktiviert? Welche Anforderungen gibt es an die ProzessnutzerInnen und welche Qualitätskriterien gibt es zur Erfüllung an den Prozess?

Die Struktur richtet sich zum einen an die ProzessnutzerInnen, damit die Informationen möglichst leicht gefunden werden können. Zum anderen erlaubt gerade die Metadaten-Tabelle den Einsatz von Testautomatisierung.

Testautomatisierung

Einer der wichtigsten Einsätze für die Testautomatisierung ist eine regelmäßige Erinnerung, dass Prozesse einem Review unterzogen werden sollen.

Damit bestimmte Elemente, wie das nächste Review-Datum eines Prozesses, geprüft werden können, muss sehr exakt angegeben werden, wo das Element zu finden ist. Dafür eignet sich besonders die Tabellenstruktur.

Die Tests wurden hier in Python geschrieben und für das Parsen der Datei die docutils-Library verwendet. Das vorliegende Code-Beispiel zeigt den Test auf das Review-Datum eines Prozesses.

def check_Wiedervorlage(self, document):
     assert 'Wiedervorlage' in self._data, \
         annotate(self._table, "metadata table missing 'Wiedervorlage' row")
     value = self._data['Wiedervorlage']
     match = re.match(r"(\w+): ([\d\-]+)", value)
     assert match, \
         annotate(self._table, "metadata 'Wiedervorlage' row has the wrong format")
     groups = match.groups()
     try:
         dt = datetime.strptime(groups[1], "%Y-%m-%d")
     except ValueError:
         dt = None
     assert dt is not None, \
         annotate(self._table, "metadata review time ('{}') format is invalid".format(groups[1]))
     assert dt >= datetime.strptime(datetime.now().strftime("%Y-%m-%d"), "%Y-%m-%d"), \
         annotate(self._table, "metadata review time ('{}') is in the past".format(groups[1]))

Dieser Test besteht aus drei Testschritten: Zunächst wird geprüft, ob die Tabellenspalte überhaupt gefunden wurde, anschließend, ob das Datum dem erwarteten Format entspricht, und zuletzt, ob dieses Datum in der Vergangenheit liegt.

Fazit

Die Prozessdokumentation wird seit nunmehr drei Jahren bei Pengutronix in dieser Form erfolgreich geführt und sowohl von EntwicklerInnen, Admins als auch der Verwaltung (teilweise in eigenständig verwalteten Dokumentationen) genutzt.

Das Ziel, MitarbeiterInnen die Mitgestaltung an den Prozessen zu ermöglichen, wurde erreicht. Natürlich gilt für das Prozesshandbuch, wie für ein Softwareprojekt, dass es niemals fertig ist. Daher ist es auch für die Pflege der Prozessdokumentation wichtig, dass es eine verantwortliche Person mit entsprechendem Zeitbudget gibt.


Weiterführende Links

Pengutronix auf dem ESE-Kongress

Auch der Embedded Software Engineering Kongress findet dieses Jahr online statt, und wir möchten die Chance nutzen, diesen als Event-Partner zu unterstützen, mit Leuten ins Gespräch zu kommen und gleichzeitig ein paar interessanten Vorträgen zu lauschen.


#FlattenTheCurve – Vorstellung unserer Remote-Infrastruktur

Die Corona-Krise hat uns alle, sowohl als Privatpersonen als auch als Firmen, plötzlich ziemlich hart getroffen und stellt unsere gesamte Gesellschaft vor neue Herausforderungen. Wir als Pengutronix möchten uns bei denjenigen bedanken, die in systemkritischen Berufen arbeiten und unsere alltägliche Versorgung sicherstellen.


CLT-2022: Voll verteilt!

Marie Mann | | clt, event, linux, talk, tutorial

Unter dem Motto "Voll verteilt" finden die Chemnitzer Linux Tage auch 2022 im virtuellen Raum statt. Wie auch im letzten Jahr, könnt ihr uns in der bunten Pixelwelt des Workadventures treffen und auf einen Schnack über Linux, Open Source, oder neue Entwicklungen vorbei kommen.


Wir haben doch etwas zu verbergen: Schlüssel mit OP-TEE verschlüsseln

Moderne Linux Systeme müssen häufig zwecks Authentifizierung bei einer Cloud- basierten Infrastruktur oder einer On-Premise Maschine eigene kryptografische Schlüssel speichern. Statt der Verwendung eines Trusted Platform Modules (TPM), bieten moderne ARM Prozessoren die TrustZone-Technologie an, auf deren Basis ebenfalls Schlüssel oder andere Geheimnisse gespeichert werden können. Dieses Paper zeigt die Nutzung des Open Portable Trusted Execution Environments (OP- TEE) mit der Standardkonformen PKCS#11 Schnittstellen und i.MX6 Prozessoren von NXP als Beispiel.


Konferenzen 2021: Ein Rück- und Ausblick

Marie Mann | | conference, talk

Neben den Verbesserungen rund um Embedded-Linux-Software und der Weiterentwicklung des Linux-Kernels hat das Team von Pengutronix im letzten Jahr die Gelegenheit genutzt, dass viele Konferenzen vom eigenen Schreibtisch aus erreichbar waren. Dadurch konnten wir unsere Erfahrungen und Ideen noch breiter mit der Community teilen und auch an Konfrenzen Teilnehmen, die für uns sonst Flugstunden entfernt lägen.