Learn how to customize Workouts with this guide
Table of content
- What is the Workout editor
- Edit Workout details
- Get familiar with text formatting
- Different text structures to choose
- Implementation
1. What is the Workout editor
To enable you to customize a Workout to the specific needs of your organization - infrastructure, environment, and processes - you can use the Edit Workout feature.
Please note that after editing your Workout, Autobahn Fit's technical writing staff will review the changes before publishing the new version of the Workout for your organization. This edited version of Workouts is not visible to other organizations.
2. Edit Workout details
To access this feature, after logging into your Autobahn Fit account, navigate to the Workouts detail page.
On top of the Workout detail page, click the Edit button.
1 - Upon pressing the Edit button you will be presented with the entire content of the Workout remediation guide in a text editor. You will be able to change both the Workout’s structure and the text's appearance.
3 - After editing the Workout, click the Submit button to submit the change request. Once you’ve submitted the updated Workout, it will be sent to Autobahn Fit for review.
Please note that when the updated Workout is pending for review, the existing Workout:
-
Can’t be edited (there’s an indication for that and the Edit Workout button will be disabled)
-
Can be downloaded as a PDF
-
Can be exported to a ticketing system
-
Will have the Share feedback feature available if there’s some additional feedback to be shared with the Autobahn Fit Team
3 - After the review, the Autobahn Fit technical writing team publishes the new version of the Workout for a specific organization (a dedicated Workout). The newly published Workout can be edited again.
3. Get familiar with text formatting
The following formatting options are available in the Workout editor:
-
Headers (H3, H4, H5)
-
The headers create the structure of the Workout and add some space between the chunks of text for better readability.
-
The headers, somewhat counterintuitively, start from 3 as the other levels are reserved by the Autobahn Fit for other uses.
-
-
Bold: To make some parts of the text stand out.
-
Italics: A more subtle way of making parts of the text stand out.
-
Code line: For the code-related instructions that are used contextually inside a line of text.
-
Code block: Useful for the chunks of code that have to be copied and pasted.
-
Quotes (notes): The yellow background will help you get users' attention.
-
Links: For references to other online resources.
-
Unordered list: For enumerations or easy classifications without particular order.
-
Ordered list: For sequential actions or enumerations in a particular order.
Please note that some of the Workouts may contain images. However, the editor doesn’t allow for adding them. To add an image, please use links to images hosted externally.
4. Different text structures to choose
In general, differentiate two types of Workouts:
- Structured by the remediation steps
- Structured by the remediation options
The Header 3 level steps and options will become a clickable section of the Workout and also a part of the text will be shown in the navigation on the Workout detail page (the “Next” and “Previous” navigation buttons will be added automatically):
4.a. Workout with remediation steps
Sometimes the remediation work can be done following the step-by-step instructions included in the Workout. A step includes a chunk of work and its completion is required to get to the next step (e.g. changing settings and testing a new configuration). Some of the existing Workouts might include options inside steps if a Workout is more complex, but that’s rare - we keep Workouts as simple as possible.
4.b. Workout with remediation options
There are also examples of Workouts that branch out to various remediation options. These options are different ways of achieving the same goal (and they consist of several steps). Usually, an option requires preparation - an introductory effort to determine which option would be the most suitable one.
A good example is patching software - it can be done by installing updates with the use of the command-line interface or via the graphic user interface. Also, different operating systems are often described separately.
5. Implementation
The structure of the Workout is determined by Header 3 and the keywords within it. You should decide from the beginning whether the overall structure will be built from Steps or Options.
In the case of Options, you can also include steps (and Steps may involve variations - options). Within the body of the text, you have the freedom to lead the Workout readers in any way you see fit. The overall structure is influenced by the utilization of the Header 3 component.
How do I decide on the correct structure?
If your goal is to guide users step-by-step through a solution and connect instructions seamlessly, then using remediation steps would be the most appropriate structure.
If, however, at the very beginning, you’re aware that the users should make some early choices regarding e.g. operational systems or different ways of patching, then use Header 3 and include remediation options as the keywords.
Please note that after using the keywords in Header 3, all the navigation elements will become options, so it’s either steps or options
It’s good to be consistent and stick to this structure throughout the entire text so that it is displayed properly - when the keywords remediation options are not used in Header 3, the system will read this chunk of text as a step and the benefit of using options will be lost.