Improving the German Corona Warn App Specification

Last tuesday, the german Corona Warn App officially launched, following intense and heated discussions about the data protection standards such an app should adhere to. In order to achieve transparency about the inner workings of the app, including which data is collected, where the data goes etc., the app is completely open-source. Not only the code but also its documentation is available on GitHub. We took the chance to look at the documentation and see if we could help improving it using the Qualicen Requirements Scout tool. Here is what we did.

Taking a closer look at the CWA Documentation

When we looked at the CWA repository, we were impressed: Not only can you find the source code of the application’s components (e.g. the Android app) online, which was what we expected, but also the documentation of the app. The documenation repository contains the requirements for the app (in terms of epics and user stories), the app’s backend architecture and several additional documents. This is something you rarely see in repositories of open-source projects. When we discovered that the documenation of the CWA app is open-source, we were curious what we would find there and especially what the requirements would look like. The scoping document contains the high-level requirements for the app starting with a description of the key stakeholders (App User, Hotline, Robert-Koch-Institut [the german institute for public health]) and a user-journey description. After the user-journey the documents describes the high-level functionality of the app (in form of epics) and breaks those down into more fine-granular user stories. Each user story contains a user story statement in the form “As a [stakeholder], I want [goal], so [rationale]” as well as acceptance criteria. Here is an example:

User Story	Acceptance Criteria
As a user, after the TAN is verified, I want to share my pseudonymized IDs voluntarily, so that I can warn persons I may have been in contact with.	1. The IDs can be sent to the Warn server pseudonymized. 2. Data transmission is only possible if successfully verified beforehand. This is ensured by the verification server and the hotline for the phone TAN procedure. 3. Data transmission is only possible if the person has granted consent beforehand.

Checking the Documentation Quality

After reading the user stories we decided that we could be of service. After all we specialize in improving requirements of all kinds, this includes user stories. We took the chance to use our automatic requirements analysis tool Qualicen Requirements Scout to find possible flaws in the documentation and improve it. We quickly configured some basic rules, such as non-conformance to the user story template (As ..: I want … so that), usage of passive voice, vague words etc. The results were very interesting. But I don’t want to bore your with all the findings that the Requirements Scout discovered. Instead, I will show you an example of what the Requirements Scout returned for the user story above. To be clear: I think it is great that the documentation of the app is shared publicly and I think that other projects should follow this example. Hence, I am criticising something that is already better than most documentation.

Here are the Requirements Scout findings for the user story above, where
green = Non-conformance to user story template
red = passive voice
yellow = vague words

Let’s start with the template conformance. Notice that the user story is missing the “so that” part. The “so that” part is important because it states the rationale of the user story. The rational serves two purposes: (1) It can be used for priorisation (2) It explains why we have this user story. Imagine that you look at the user story in two years time and ask yourself: Why did we add this user story in the first place? The “so that” part gives you the context to unserstand why you added the story. Sometimes, the rationale of a story seems too obvious that it feels strange to write it explicitely. Probably this was the case in this example. However, we could argue that actually the part after the “and” is in fact the rationale. We could rewrite the story as “… so that I can warn persons that I may have been in contact with”.

Acceptance Criteria 1 is interesting, too: “Data transmission is only possible if successfully verified beforehand”. Here the problem of passive formulations becomes apparent: Who or what is verified in this case? The user? The data? The transimission (channel)? Something else? This formulation leaves room for misinterpretation and should be changed.

Improving the Documentation

Using the Qualicen Requirements Scout results, we improved the specification and filed a first pull request. The pull request was reviewed and merged within a day or so, which added to my impression that for the CWA project, a good specification is important. Encouraged by this, we added a second pull-requests to improve the documentation further, which is still pending. In the meantime, the team did a major overhaul of the scoping document, resolving many of its issues. Good Job!