Training Example Documentation Writing Guide

How to Title Your Pages

1. For the first hierarchical page, it should be titled as:
   "Example Workflow Name [EX(Example Number) - Workflow Name Abbreviation]"

   For instance: "Example Steel I Girder [EX1 - SIG]"

2. The titles of the child pages should mirror the names and hierarchy found in the treeview within OpenBrIM, as illustrated in the screenshot provided below.
   "Workflow Treeview Item Name [EX(Example Number) - Workflow Name Abbreviation]"
   For instance:: “Roadway Alignment [EX1 - SIG]

Open

What Information Should Training Example Pages Include?

Open

• Homepage: The homepage content should 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:
  When developing this section for a training example, it is of utmost importance for the writer to emphasize clarity by clearly distinguishing between two distinct aspects:

  1. 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.

  2. 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 in the data spreadsheet 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: 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, a link to the instructional page of the workflow must be added. The document containing the provided link should be inserted using the "expand" command.

Section 3: 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.

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.

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: 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 6: Copy Data

In the section where the parameters to be copied are located, there should be 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 copy 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 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.

• For an example, you can visit the following link.