QM meets CI

Marie Mann | | talk

"Hey Marie, how do I schedule my vacation dates again?", since I'm working in the management division of Pengutronix, I know these kind of questions very well. Writing down the processes enables me to answer "RTFM". Processes are organizational tasks that need to be performed over and over again, somtimes based in a fixed interval - sometimes on demand.

When the process documentation at Pengutronix was revised from scratch in 2018, the main question was how to involve the employees in the creation of the processes. For the documentation, a workflow and tools were chosen that were already established among the majority of employees.

This article presents the chosen tools, shows the workflow and explains the structure of a process description as an example.

Why write down processes?

As soon as a company is large enough that not all employees are sitting in the same room and can see which tasks are being worked on at any given time, it becomes necessary to write down precisely these processes. Process documentation makes it possible to record the knowledge about the processes and to establish rules.

Although the rules are set by the management, they are visible to all employees and can therefore be demanded. This enables fair treatment of all employees.

How can employees be involved?

Writing down the processes is not an end in itself, but serves to enable employees to read up on how to apply for vacation, for example.

Often the process users are the content experts, because they follow the process every day and live with it. They know best how a process can be optimised. This fact alone should be reason enough to involve the process users in the design of the processes:

  • The processes can be improved by the users and
  • The processes will be followed much more willingly if they make sense to the users.

Getting started in software development is often compared to a recipe.

A cookbook could also be called process documentation: A process, like cooking, has a trigger (hunger) or entry point and describes a set of instructions for action.

If the process documentation is the source code that runs the business, why not use the tools from software development to write the process documentation?

At Pengutronix, the train of thought was taken seriously and the process descriptions are designed in the form of a process manual using the tools of software development.

For the implementation, there were the following requirements for the processes and their presentation:

  • The processes should be easily accessible,
  • The employees should have an opportunity to participate and be involved in the design of the processes,
  • The processes are (therefore) subject to an approval process by the management,
  • The processes should be regularly checked to ensure that they are up to date.

Tools and workflows

In order to meet the requirements and implement the process manual as a "software project", both workflow and tooling, which are already established in the company, are used. These workflows and tooling are briefly described below. The description will be reduced to the essential features that are necessary for the design of the process documentation.

Linux kernel workflow

One of the most important and widely used workflows at Pengutronix is the one used to develop the Linux kernel.

The Linux kernel is divided into different subsystems, which are roughly comparable to individual departments of a company. Depending on the complexity, there may be further subsystems. Possible changes to the Linux kernel (bug fixes, new drivers, code quality improvements) are first discussed within the subsystem. A maintainer is responsible for each subsystem (this can be compared to a middle management level), who carries out tests and checks whether the quality standards are met. If everything is in order, the changes of all subsystems flow into the next version of the Linux kernel. This is released by Linus Torvalds (the first author and maintainer of Linux) himself.

We have adapted the described workflow for the work on the process manual: Changes to the process documentation are discussed with the respective process users and then passed on to the management for approval. Currently, the Pengutronix process manual project is still small enough that "subsystem maintainers" e.g. a middle management layer is not required.

Version control

In order to be able to implement this workflow, the processes are written as structured text files that are managed in a version-controlled manner. The release branch of the version management can only be written for the management, so that a new release of the process manual also ensures the release at the same time.

The advantage of files written in reStructuredText (.rst) or Markdown (.md) plain-text formats as opposed to non-text-based formats such as .docx or .odf is that the change in content can be easily tracked in a version management system along with a timestamp and the respective authors. Furthermore, in addition to just tracking changes, a version management system also allows descriptive text to be written to record why a change was made and what decisions led to the process change.

Web representation

As great as the charm of text files is from the point of view of the process writers, for the process users the user-friendliness is not ideal. Therefore, Pengutronix uses the open source software documentation tool Sphinx to generate a web view of the process manual. In this, the processes can be linked directly as well as forms belonging to a process can be made available for download.

Build server

With the help of a build server, the current release of the process documentation is built and made available as a web view. At the same time, the build server enables the use of automated tests.

At Pengutronix, the build server checks, among other things, whether the date on which the next process review is due has been exceeded. If this occurs, reminder e-mails are sent so that the process can be checked promptly to ensure that it is up to date.

The setup has only been described schematically here, as the focus is not on concrete products but on their use for process documentation. What is more important is that any form of version management is used to track changes and that any kind of build server is used for continuous testing and continuous deployment.

Structure of a process description

In order for the setup to be used to its full extent, it is crucial that a structure for the handbook and the structure of a process is determined in advance. A good example of the structure of processes and how such a manual can be designed is the "Company Handbook" by GitLab Inc.

In order to go into practice, the structure of a process in the process documentation of Pengutronix is described in excerpts, and a test is presented as an example.

A process consists of three sections: The first section is a table in which metadata is recorded. When was the process last updated? When is the next review due? Is there a predecessor process? Which process follows on from the current process? Are there any forms to download?

The second section contains the actual process description. There is no fixed form for this. To make the process easy to read, additional structuring elements such as info boxes or enumerations are used.

The third section is reserved for general information based on the quality criteria of ISO 9001. Among others, the following questions should be answered: Who are the process users and owners? When is the process activated? What requirements are there for the process users and what quality criteria are there for the process to fulfil?

On the one hand, the structure is aimed at the process users so that the information can be found as easily as possible. On the other hand, the metadata table allows the use of test automation.

Test automation

One of the most important uses for test automation is a regular reminder that processes are due for review.

In order for certain elements, such as the next review date of a process, to be reviewed, it is necessary to specify very precisely where the element can be found. The table structure is particularly suitable for this.

The tests here were written in Python and the docutils library was used to parse the file. This code example shows the test for the review date of a process.

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]))

This test consists of three test steps: First, it checks whether the table column was found at all, then whether the date corresponds to the expected format, and finally whether this date is in the past.

Conclusion

The process documentation has been successfully managed in this form at Pengutronix for three years now and is used by developers, admins as well as the administration (partly in independently managed documentations).

The goal of enabling employees to participate in the design of processes has been achieved. Of course, the process manual, like a software project, is never finished. Therefore, it is also important for the maintenance of the process documentation that there is a responsible person with a corresponding time budget.


Further Readings

Pengutronix at ESE Kongress

The Embedded Software Engineering Kongress is also taking place online this year and we would like to take the opportunity of easy participation to watch the lectures, join in the discussions and get into conversation.


#FlattenTheCurve – Introducing Our Remote Setup

The Corona crisis is a challenge that has hit many people as well as most companies quite unexpectedly. The entire team of Pengutronix wants to thank those that currently ensure our essential supplies, health system and civil infrastructure!


Smart City - vom Rapid Prototyping bis zur Tragfähigen Infrastruktur

Wir wollen zum Bundesweiten Digitaltag am 18.6.2021 das Thema "Smarte Städte" ein bisschen von der technischen Seite beleuchten, aber keine Angst: es bleibt für alle verständlich.


Wie man (k)ein Betriebssystem für Produkte baut

Distributionen wie Raspbian lassen die passgenaue Zusammenstellung eines Betriebssystems kinderleicht aussehen. Image herunterladen, Pakete installieren, noch ein paar Änderungen - fertig. Alles wie auf dem Laptop oder Server. Warum ein Betriebssystem aus einer klassischen Distribution im Produkt-Kontext zur Katastrophe führen kann, beleuchtet der Vortrag "Raspbian vs. Build-Systeme: Das richtige Werkzeug für solide Produkte".


Pengutronix at FOSDEM 2021

"FOSDEM is a free event for software developers to meet, share ideas and collaborate. Every year, thousands of developers of free and open source software from all over the world gather at the event in Brussels. In 2021, they will gather online." -- FOSDEM