Step description deprecated

Published on:

5/7/2022

Updated on:

16/1/2023

This article is from before the rebranding to SelfGuide. Text and images can include the old product name ProductivityPerformer or its abbreviation PP.

The step description is used to add contextual information to a step, for example an explanation or a relevant corporate policy. This field has been available from the beginning of SelfGuide and is still often used, however a better option is available. To help improve the content created by editors, we have chosen to deprecate the step description and remove the field later this year. Shown below is a more detailed explanation about this choice as well as the timeline between now and the final removal of the step description.

Step description vs. annotation

Two options are currently available to add context information to a step: step descriptions and annotations. These options differ in functionality, behavior and usage:

Aspect	Step description	Annotation
Usage	Generic explanation of the step or context information for the step	Used for explanations, context information, relevant policies, links to reference documentation or related instructions
Location	In the top of the window below the title	Inline with the step image, exact location chosen by the editor
Text type	Plain text only	Rich text options like bold, italic, lists and hyperlinks
Amount	Fixed field, only one step description can be set	Zero to many, the editor determines the needed number of annotations

Feedback and usage

We have received various feedback about the step descriptions, some examples:

Editing the step description is not intuitive due to issues such as new lines not being shown and no vertical scrollbar being available when the text does not fit
The step description does not attract attention in the Instruction viewer, and as a result users do not read the description when relevant information is present
Only the first part of the step description is visible in the Instruction viewer when the text does not fit the available space

In addition to this feedback, we have observed that the usage is quite arbitrary. Each editor has their own way of working, resulting in these variations:

No step descriptions at all
All information in the step description and an annotation
Generic information in the step description and specific information in an annotation

For a user, the result is a less intuitive experience as the arbitrary usage directly impacts uniformity.

Timeline

From this moment on, the step description is deprecated and will be entirely removed in the future. We are aware of the current usage, therefore removal will be done in stages as described below:

1. Step description read-only

The first stage is to discourage the usage of the step description. The step description will be made read-only and will only be shown if a step already has a step description. The result:

Steps without a step description -> the step description is not shown in the Instruction editor and cannot be set
Steps with a step description -> a warning is shown as well as options to easily copy and remove the step description

2. Time to update instructions

At this stage there will be a few months where nothing is changed to give editors time to update instructions with steps currently having a step description. We will closely monitor this change and notify as needed about the requirement to update instructions.

3. Remove step description from Instruction viewer

The Instruction viewer will be updated first. The step description will be removed and the step title will be given more space and be made more intuitive.

Removal of the step description in the Instruction viewer is done in week of 12 December 2022.

4. Remove step description from Instruction editor

The last stage is to remove the step description from the Instruction editor. From this moment on, the old data cannot be seen and copied anymore. The remaining step description data will be permanently deleted after finishing this stage.

Removal of the step description in the Instruction editor is done in the week of 06 February 2023.