Automatic consistency between documentation and development? BIOTRONIK shows you how

In cooperation with SCHEMA, BIOTRONIK has been searching for the most convenient solution possible, and has found it in a unique approach: two interfaces have been defined as part a joint project, which are designed to ensure the version-specific consistency of terms.

Alexandra Koegstadt, technical writer and sub-project manager, introduced us to the two interfaces and explained how the project team dealt with the complex requirements involved at the last SCHEMA Conference.

The search for a convenient solution for maximum precision

BIOTRONIK is a leading company in cardiovascular medical technology and is based in Berlin. It has been using the SCHEMA ST4 Component Content Management System for technical writing at three of its sites since 2017. The firm produces heart pacemakers, defibrillators and external machines for cardiac electrotherapy. High-quality documentation is essential in this industry: a physician who needs to adjust the basic rate of a heart pacemaker, for example, needs precise instruction. If the terminology does not match, this can pose huge risks in such sensitive applications and may have legal consequences. The goal of the technical writing department at BIOTRONIK was therefore the automated use of existing terms from development databases in order to maintain a high level of quality and consistency.

The solution and the requirements

The solution came about in the form of newly developed interfaces between ST4 and the BIOTRONIK development databases. Terms in the documentation are automatically updated as soon as they are updated in the database – and without the need for any additional manual work.

Ensuring matching terminology needed to be automatic for the following content:

• Interface elements such as GUI strings, which must be referred to in the documentation.
• Parameter values assigned to GUI strings.

A separate interface was developed for each requirement, which we will now take a closer look at in the examples below.

Interface 1: Integrating interface terms directly into ST4

Firstly, the interface elements referred to in the documentation should match the GUI terms in the software – and in all languages.
Example: The "basic rate" (“Grundfrequenz") interface element in the documentation should always match the GUI term in the software interface.

The first interface was created for this purpose: a connection between the CCMS ST4 and the database in which the names of the GUI elements (known as “GUI strings") are stored.

How does the technical writer perform the automatic alignment?

The first step is to find the ID of the GUI element in the software. To do so, the writers use a tool developed by BIOTRONIK. The ID is then entered in the ST4 editor and classified with a special inline element.

A particular highlight is that in the GUI string database from Biotronik, the content is already managed in multiple languages. This reduces translation costs whilst also maintaining consistency.

Assignment to the respective software version is ensured using the “Checkpoint" metadatum, so if GUI element changes in a later version or variant, this is only adopted in the documentation for that specific version.

When the project is published, all GUI elements mentioned in the documentation will be published with the defined checkpoint – “Irrespective of how often the GUI string or translation has changed in the meantime," explains Ms Koegstadt.

Interface 2: Integrating parameter values from the database into ST4

A second interface should guarantee consistency when quoting parameter values. These values are not located in the GUI string database, but rather in a separate parameter values database. However, the procedure for technical writers differs only slightly to the GUI string interface.

Here's a brief example to illustrate what a parameter value is. The basic rate of a heart pacemaker lies within a specific value range ("Wertebereich"), which is summarised as a standard value. Although the standard value of the basic rate may be “60", this in reality covers a range of values from “30 (5) 100 (10) 160 bpm".

"Basic rate" is thus a GUI element in the GUI string database, and the associated settings are parameter values in the parameter values database.
Now let's take a brief look at how technical writers align terminology using the second interface.

Firstly, the parameters from the software also have a separate ID (parameter ID) which can be identified using the internal tool, i.e. in the same way as the GUI strings. The parameter ID is recorded in the ST4 editor again and classified with an inline element.

The difference compared to interface 1 is that as the parameter values may differ for each product project, precise retrieval of the values in ST4 must be possible. In order to depict the correct values for the product variant in the documentation, the following parameter details must be specified: product project, sales area, product feature set and product type.

Thanks to the parameter ID and specific retrieval of values for the product project, the parameter values are reliably added to the data sheets and instructions for use. The technical writers can also see the values already in the quick view during the process. The tables can be altered depending on the document type. Individual columns that are not relevant can be removed from the data sheets.

After adding the parameter ID, the relevant metadata is set, the checkpoint is saved again, a filter is set and the project is created.

The result is as follows:

The text in the columns originates exclusively from the automatic retrieval of the values from both databases.

Lessons learned

What seemed like simple idea in reality turned out to be a development project with very complex requirements. However, BIOTRONIK technical writers and SCHEMA consultants have found a solution through an iterative approach, the benefits of which will still be felt in years to come.

Not only has the main objective been achieved, but also the goal of ensuring consistency without the need for manual checks. The time needed to create the documentation has also been reduced and savings have been made on translation costs.

Alexandra Koegstadt, Berlin, qualified Media Consultant and Technical Writer has worked for BIOTRONIK SE & Co. KG (medical technology) since 2007 and is the Sub-project Manager for the provision of a new content management system at the Berlin site; ST4 has been productively used at three sites since mid-2017/the start of 2018 with site-specifi c expansions.