Document Formatting GuideLines
- Umut Nuhat Sevinc
In the document, the font type should be selected as 'normal text'.
The title names should be formatted as follows:
(Workflow Name) Workflow - Ex: Steel I Girder Workflow
Example (Workflow Name) [EX(Example Number) - Workflow Name Abbreviation] - Ex: Example Steel I Girder [EX1 - SIG]The subheadings should have the same names as the treeview headings visible in the OpenBrIM data spreadsheet.
The 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, etc.
The subpage should detail which instructional pages will follow it and explain the objectives or goals of these subsequent pages.
For the instruction page:
- If 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.
If a page needs to have a screenshot added and there is no need for any edits, the screenshot can be directly added to the page. However, if there is a need to edit the screenshot, it should be edited by going to the provided link and then added to the page.
If text is required on the edited page, Times New Roman font with a font size of 15pt and bold formatting in red is preferred. Arrows and boxes should be set at a font size of 3pt and can be either red or black in color.
Example Document Formatting Guidelines
The rules written below should be followed sequentially when creating the document.
First, it should be specified where the user needs to navigate to in the data spreadsheet on OpenBrIM. This instructional text should be added using the Info Panel command.
To enable the user to check what the object they are defining in the data spreadsheet or its input parameters are, a link to the instructional page should be added.
The document with the provided link should be added using the "expand" command.
To guide the user during modeling, numbered tables should be used.
If the description in the table contains a command for the user, an OpenBrIM emoji should be placed at the beginning of the sentence.
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 cases where additional explanation is needed for the user, Quick Tip should be used.
The Quick Tip text should have a general narrative that covers all the projects to be created.
The cell background where the Quick Tip text is placed should be yellow.
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.
In the table instructions, any statement that needs to be emphasized should be written in bold. For example: parameter name, parameter value, etc.
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 view of OpenBrIM.' and the corresponding screenshot must be added to the table.
In the final step of the table, the user should be directed to the section where they will copy the input parameters. Additionally, guidance should be provided for the step that follows the copying process.
This instructional text should be added using the Note Panel command.
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.
In the section where the parameters to be copied are located, there should be parameters that will modify the default parameters of the object.
After completing the table, a Quick Tip page explaining how to transfer input parameters to OpenBrIM should be added to the document.
Following the Quick Tip, the table containing the parameters to be copied is added to the document.
The table should have the main title as "Object Name" and the subtitle as "Parameter Name".
After the table is added, a message should be shared in the document indicating that the user needs to check the OpenBrIM 3D View.
This instructional text should be added using the Success Panel command.
The Model Quick Tip should be added to the document.
The OpenBrIM 3D View screenshot should be added to the document.
The FEA Quick Tip should be added to the document.
The OpenBrIM FEA screenshot should be added to the document.
The OpenBrIM Spreadsheet View screenshot should be added to the document.
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.
Workflow Document Formatting Guidelines
The document should provide the user with information about objects and their parameters.
If possible, a photograph depicting how the object appears in real life should be added to help the user better understand the described object.
Each parameter should be explained under the category heading to which it belongs. As shown in the screenshot, the "Top Flange Width" parameter should be examined under the "Girder Parameters" heading.
The category names should be formatted with the 'Heading 2' text style.
The parameter names should have the text style set to 'Normal Text' and the font set to 'Bolt'.
The meanings of the parameters should be supported with screenshots to help users understand them better.
If a parameter has units, it should be displayed in brackets, for example: '[kip]', '[ft]', '[deg]', etc.