How to Title Your Pages
The title names For the first hierarchical page, it should be formatted titled as follows:
"Example Workflow Name [EX(Example Number) - Workflow Name Abbreviation]"For instance: "Example Steel I Girder [EX1 - SIG]"
The subheadings should have the same titles of the child pages should mirror the names and hierarchy as found in the treeview visible in the within OpenBrIM, as seen illustrated in the screenshot provided below.
"Workflow Treeview Item Name [EX(Example Number) - Workflow Name Abbreviation]"
For instance:: “Roadway Alignment [EX1 - SIG]
...
What Information Should Training Example Pages Include?
...
Homepage: The homepage content on the homepage should provide information to the user about what they can accomplish with this document. In the example document, this page should also include general information related to the project, such as design parameters, design loads, etcshould inform users about the training example's objectives and include general project-related information, including design parameters and loads, relevant to their modeling efforts.
Subpage: The subpage should detail which instructional pages will follow it and explain the objectives or goals of these subsequent pages.
Instruction page:
- If When developing this section for a training example, it is created for a workflow, it should explain all the input parameters present in the described object.
- If it is created for an example, it should guide the user on correctly modeling the project.
of utmost importance for the writer to emphasize clarity by clearly distinguishing between two distinct aspects:
Workflow instruction pages, which are expected to provide a comprehensive breakdown of all input parameters associated with the described object. These pages should serve as a reference for users to understand the intricacies of the workflow and the role of each parameter.
Training example pages, on the other hand, should primarily focus on guiding users through the process of correctly modeling the project within the user interface. These pages should be designed to be user-friendly and offer step-by-step instructions, ensuring that users can effectively apply the concepts learned in the training.
Furthermore, it is imperative to recognize that the detailed explanation of parameters and their definitions should be reserved for the dedicated workflow instruction pages. This separation of content ensures that users can access in-depth information when needed while maintaining a streamlined and practical approach on the example pages. This approach maximizes the clarity and effectiveness of the training materials.
What sections should one include on a instruction page?
...
Section 1: Treeview Instruction
First, it should be specified where the user needs to navigate to in the data spreadsheet on within OpenBrIM. This instructional text should be added using the Info Panel command, as shown below. The text in the panel on every page should be the same, except for the navigation location in the treeview.
...
Section 2
To enable the user to check what the object they are defining
...
Section 1: Treeview Instruction | ||
|---|---|---|
|
Section 2: Link to Parameter Descriptions
In order to facilitate user reference to the object being defined in the data spreadsheet or to access the definition of its input parameters are, a link to the instructional page should of the workflow must be added.
The document with containing the provided link should be added inserted using the "expand" command.
...
Section 3
...
To guide the user during modeling, numbered tables should be used.
...
| title | Section 3 Formatting and Style Instructions |
|---|
...
If the description in the table contains a command for the user, an OpenBrIM emoji should be placed at the beginning of the sentence.
...
: Modeling Instructions
When instructing users through the modeling process, employ numbered tables that comprehensively cover the essential instructions for modeling the bridge component, as illustrated in the screenshot below.
The instructions in the table should be written step by step to help the user create the model accurately. It should be clearly indicated which cell to click on and what value to enter for each parameter.
A screenshot related to the instruction in the table should be placed right next to that instruction
...
In this section, typically, one instance (row) of the component should be defined with instructions, and the rest should be copied under the 'Copy' section. It is generally sufficient to explain how one of these components is defined unless there is no other reason to model more than one.
In certain instances, it's feasible to demonstrate the definition of just one parameter, and if the same principles apply to other similar parameters, it can be indicated as follows:
...
In cases where additional
...
explanations are needed for the user, Quick
...
Tips should be used.
...
In training examples, these additional explanations are typically related to the user interface. Quick Tip
...
explanations should have a general narrative that
...
is applicable to all examples, except for one specific training example.
...
| Expand | ||
|---|---|---|
| ||
|
...
|
...
The Quick Tip link should be added to the provided page. If necessary, it should be pulled into the document using the excerpt include function.
...
|
...
Before the user goes to the input copying section, one instance of the object to be defined in the project should be modeled. The object can have the same input parameters. It is sufficient to explain how one of these parameters is defined.
...
Section 4: Verify Model
Before proceeding to the data copying step, the statement 'When the steps are completed, the shared screenshot displayed in the adjacent cell should be visible in the 3D(or FEA) view of OpenBrIM.' and the corresponding screenshot must be added to the table. This step will provide the user with an understanding of whether they have executed it correctly up to this point.
...
Section 5 |
|---|
...
: Verify Model | ||
|---|---|---|
|
Section 5: Copy Instruction
After the instruction numbered table, the user should be directed to the section where they will copy the input parameters. Additionally, guidance should be provided as seen below for the step that follows the copying process.
This instructional text should be added using the Note Panel command as seen below.
...
Section 5: Copy Instruction | ||
|---|---|---|
|
Section 6: Copy Data
In the section where the parameters to be copied are located, there should be parameters that will modify the default parameters of the object.
...
all the input parameters that can be used for copy operation as seen below
...
Quick Tip page explaining how to transfer input parameters to OpenBrIM should be added to the document as seen below.
...
Section 7
After completing the table is added, a message should be shared in the document indicating that the user needs to check the OpenBrIM 3D Viewcopy operation, the document should display the following message, indicating to the user the need to verify the correctness of their work in OpenBrIM 3D View/FEA View and Spreadsheet. This instructional text should be added using the Success Panel command.
...
Section 7 | ||
|---|---|---|
|
Section 8
This section should contain screenshots of the completed model and instructions for verifying its completion.
The Model Quick Tip should be added to the document.
...
The OpenBrIM 3D View screenshot should be added to the document as seen below.
...
The FEA Quick Tip should be added to the document as seen below.
...
The OpenBrIM FEA screenshot should be added to the document.
...
The OpenBrIM Spreadsheet View screenshot should be added to the document as seen below.
...
Section 9
The message 'To view the entire procedure explained on this page, please watch the recorded Video below.' should be added to the document. This instructional text should be added using the Success Panel command. Finally, a video demonstrating the implementation of all the information explained in the document should be recorded and added to the document.
...
Section 9 | ||
|---|---|---|
|
...
For an example, you can visit the following link.