Instruction is guided information about the page and the processes on that page. When the user clicks on the help button, the documentation is available. Instructions could also be used for testing.
Notice! With the release of Architect 3.9 the documentation & testing which was introduced in 3.7 with the use of plugins has been fully integrated into the Architect.
In this post we are talking about basic page instructions.
In the integrated application, in order to be able to display the actual instructions, the component M4813 Novulo Instructions must be included.
1. Ensure right plugin is available
In the component you are working in, you need to add the Application Maps Helper Plug-in.
2. Ensure the plug-in form is set on a relevant page
On each page that needs documentation, the Instructions Form Panel must be available. It must be on the main page (so not in a tab): on the right side, below any other form panels, to prevent layout disruption. Change the name of the panel to “Instructions” + your model number to make the panel name unique.
Not adding the model number will make that only instructions from one source remain valid. This problem is solved in Architect 3.9.
3. Ensure essential page elements are described
Pages with form elements can be instructed. Ensure that on all relevant pages, page instruction is added for the most essential page elements. You can check this by viewing the Forminstructionspanel added on these pages.
Notice! Grid pages cannot be documented in the page instruction, while this is meant to explain fields.
Go to the properties of the FormInstructionsPanel and navigate to the tab Plugin Configuration.
An instruction consists of the following parts:
- Introduction: this text is shown before the fields.
- InstructionParts: List of elements to document on the page.
- AfterWord: this text is shown after the fields. For example: hints for which business process can be chosen to work with.
When hoovering above the 
icon will give a tool tip about the function of configuration pieces:
1. Introduction
Add for all relevant languages a good introduction explains what the goal/aim is of the page.
2. InstructionParts
You can add more instructionparts by clicking on the plus button. When no InstructionParts are yet availavable it looks like this:
Notice! You cann’t document the same instructionparts twice as it will give an error when generating instructions later on in the application.
When instructionparts are already present:
Linking elements on the page
Remember that not all page elements need to be mentioned, only fields that need explanation.
- Click on
tot start linking an element.
2) A link dialog appears;
3) Navigate to the element you want to document;
4) Select the element you want to document. (Make sure you select the element itself, not the row, or the button if this is not the purpose);
5) Click the “Link Selected button” and the value is stored.
Notice! Integration automatically occurs: If a page in an application instance is defined in multiple components, then all page instructions are combined, and concatenated in the order of integration. This concatenation is grouped per Introductions, then InstructionParts, then AfterWords.
Adding text to describe the elements
- Open Message entry.
- Type an instruction to document the field, for all relevant languages.
- When using brackets it is possible to define which part of the content sentence needs to be highlighted. This is currently already the case.
- Use Ok button to save. If you use Cancel or cross of the windows, then all changes are lost.
Order of InstructionParts
Document field and elements in the order of appearance, so that it is easy for the user to read.
You can move an instruction part to top, bottom, and one position up and down via right click context menu:
Also removing an InstructionPart is possible via this menu by clicking on the delete button.
3. AfterWord
The afterword is shown in the instruction sidebar under the instructionparts. Here you can give hints about in where the page instructions are used.
Giving the reason of existence, and summary of record, should be done in intro.
Leave aftword empty if there is no hint or instruction which processes can used / interact with this record.
Filling in AfterWord works similar to filling in the introduction:
(Remember not to forget to type enter after each line, as the text might not be saved.)
Finally
If you are finished, click on OK
Notice! When saving the properties via the OK button there might be a warning.
This warning can be ignored. The instruction form is not visible and therefore does not have a description width, setting the width only helps once, when closing the properties window.
4. Possible errors
Possible errors in the Architect:
Make sure you fix all errors, before you save your model. Below some common found errors are explained:
- Missing languages because not for every relevant language, all instructions are added.
- An instruction part needs to filled. (Or if it is empty, then remove it.)
After documenting or updating documentation of a component. Update the component in the application.
After updating the documentation, (re-)generate the instructions and processes in the application to get the latest version of the instructions.