Cwa-documentation: Figure 4 Label at step (1) Is wrong

[HolgerMayer]

Where to find the issue

Figure 4 Step (1)

Describe the issue

The text at the arrow reads:
Create TAN via Web Interface
It should read
Create teleTAN via Web Interface

Suggested change

Simple solution : change text

Right solution:
The naming TAN and teleTAN is lets say intransparent. I assume the tele prefix was create because it may be transfered by voice over a phone line while the TAN is only transfered internally.
This leads not only easily to errors like above. It leads to problems like format creation. If the teleTAN is entered manually do you need to prefix it with teleTAN ? Probably not.

Here we again (see QR-Code) mixing

• function
• data format
• exchange format

The function is
TAN : Diagnostic Key Upload Identification Access Code
TeleTAN : Test Prob Identifier Replacement Access Code

The format for TAN may be an identifier
The format for teleTAN may be an identifier with a checksum to make sure, typos are catched

Exchange format:
TAN : text
TeleTAN: text, sound (Telefone)

It is probably too late for you to change this, but naming of system elements is in general even more important than naming variables in code.

[tklingbeil]

Thank you for reminding us that naming of things is relevant...

If you read the test carefully, you will see that the teleTAN indeed is not a "Test Prob Identifier Replacement Access Code" (I actually don't 100% understand what you mean with this), as it is not coupled to a specific tests. It is used to grant upload permissions to users who have not received electronic test results.

Again, the solution architecture document is a high-level document. As mentioned before and mentioned in the document as well, In-depth information on the specific data format, exchange format and function of the individual entities will be covered in the corresponding documentation.

[HolgerMayer]

When the doctor puts a QR Code on the test prob the number on the prob identifies this probe.
If the patient receives the positive result he enters this QR Code that identified the probe Figure 2 Step 4a.

Now compare this with Figure 2 Step 4b. Here the teleTan replaces the QR-Code as authorization mechanism for verification.

So in Figure 2 Step 4b

• Test probe identification (QR Code)
• Is replaced with a new number (teleTan) for
• Access authorization.

By the way - there is no Step 4b in your itemization within the text.

[HolgerMayer]

First upfront I don’t want to annoy you. We both want that your project is successful. Still annoyed? I recommend reading the following.
Sorry - I got not private Email from you so I post this publicly though I preferred a private conversation on this topic.

If I write something like “but naming of system elements is in general even more important than naming variables in code.” this mirrors one of many lessons I learned from several projects I worked and after entering the project late in the development rescued from doom (not saying yours is doomed!). Everybody on these projects wanted success but somehow didn’t reach it. What I learned was there are several bad habits, that project teams follow not because they don’t want to but because in general timing constraints lead to the assumption one has no time for this.
Naming is one such shortcut. And I like to explain with the QR-Code of your project why this happens and why this is a bad habit.

The Lab System sends you a QR-Code. It is called QR-Code by the supplier of the data. Three question now arise:

1) Is this a good fitting name?
2) Is there a better fitting name?
3) If so can I change it for additional benefits?

Question 1 : in the long run no.

If your app is successful one thing is for sure. It will grow and be changed. Other virus mutations will be handled. Other viruses will be handled. People will because of its usefulness trust the app more than today. Eventually the way, how the data from the lab is transferred may change to email. The user clicks on a link in an email and the data today in the QR-Code will be directly loaded into your app. Someday the QR-Code even may be retired.
What does this mean for your documentation and code (I don’t know your code yet so I may be wrong). Every instance of “QR-Code” need to be changed in your documentation and code and unit tests and… In my experience this happens in general only in parts of the system so documentation and code deviate over time. New developers work on the system that grows. They need to learn a system that is more and more filled with obsolete descriptions.

Question 2 : use function over format

Take the International Standard Book Number as an example. Well know ISBN. Over time the numbers length changed because of necessity. But the numbers are named ISBN or with versioning of content ISBN-10 and ISBN-13 not EAN 13 – the printed barcode format.

Question 3 : Unless you are required by some weird contract obligations yes.

You can write in the Glossary under QR-Code that this wording is used by the supplier but in the documentation and code you use “xyz”. Under the glossary entry for “xyz” you write that the supplier calls this in general “QR-Code” because it currently (specify a date) is printed as a QR-Code.
In the documentation and code you use xyz. Now if the format changes you need to change the glossary. Done – though I recommend this to be included in a data dictionary too.

The same for TAN and teleTAN.
I got suspicious of the naming for several reasons:
1) Why is TAN missing a declarative prefix?
2) For what is tele standing?
3) The usage of TAN and teleTan in the system is quite different besides defining a transaction code. Why is this not visible in the naming?

And lastly when looking into the server code there is (was?) a first temporary format defined as pattern and I though why use TAN or teleTAN as prefix in this pattern? Why should a user entering a teleTAN enter this name? Why not use only one character to distinguish them? Is teleTAN different than TAN (internal use vs. external use). Shouldn’t both be separate classes derived from a common class TAN.

And thinking about this it is clear – every new developer, reader of the documentation needs to answer these question for herself – because the naming doesn’t describe function.

Conclusion

I wrote “It is probably too late for you to change this,“ because your are currently very probably under an immense pressure because of timing constraints. So yes I recommend to at least fix the label in Figure 4 right now. But as soon as the first major rewrite/ addition / change is happening for the system you should start reworking these point to make sure, that your software can change, usage can grow without major rework for minimal changes.
I hope I didn’t offend you. I did my own share of overtime under even physical bad conditions getting new systems running. I feel with you and wish you success. If you read some new issue from me while your head is filled up with thousand other things please remember – I only try to help you even if it may not be obvious at the time.

[tklingbeil]

I truly appreciate the feedback! Thank you!

The label in Figure 4 was fixed yesterday already (the issue was closed through the commit, see above).