Consistency in process and language in the documentation

[MichaelVictoriano]

Describe the bug 📝

As the title suggests, there are multiple process steps and language use inconsistencies in the documentation. These are captured in my post here .

There are multiple tutorials mentioned on the topic for consistency in the process presentation.

1. Component
2. ClassificationsTree
3. ElementProperties
4. EntityAttributes
5. ModelsList
6. RelationsTree

These tutorials skip multiple parts of the process, where, for example, the lines at the top of the JavaScript/TypeScipt file, the import statements, which bring in dependencies or modules in that code to use, were not displayed. This part is consistent with all other tutorials from Core and Front, not with the UserInterface.

import * as WEBIFC from "web-ifc";
import * as BUI from "@thatopen/ui";
import * as OBC from "@thatopen/components";
import * as OBF from "@thatopen/components-front";

They also skipped the "Setting up a simple scene" part, which is consistent with all other tutorials from Core and Front. EntityAttributes seem to have imports and the scene, though.

"Initializing the UI" was also not shown in these tutorials. We know that all these are in the full source code on Github but our scope right now is the tutorials in the documentation.

BUI.Manager.init();

Although on Github, the consistency of the object names used for imports is also a question.

OBC from "@thatopen/components"
OBCF from "@thatopen/components-front", called as OBF in EntityAttributes
BUI from "@thatopen/ui"
BUIC from "@thatopen/ui-obc", used in Civil tutorials

CUI referencing "@thatopen/ui-obc", used in the UserInterface/OBC tutorials

It may be helpful for those who are new to programming and new to ThatOpen’s documentation to have a reference similar to this, for consistency. Again, this is subjective and purely a suggestion.

Name	Object Name	Version	Description
@thatopen/components	OBC	2.1.11	Collection of core functionalities to author BIM apps.
@thatopen/components-front	OBCF	2.1.7	Collection of frontend tools to author BIM apps.
@thatopen/fragments		2.1.3	Simple geometric system built on top of Three.js to display 3D BIM data efficiently.
@thatopen/ui	BUI	2.1.0	Collection of web components (UI components) meant to be used, but not limited to, BIM applications.
@thatopen/ui-obc	BUIC	2.1.0	Collection of web components (UI components) implementations to use with @thatopen/components.

The “Loading a BIM Model” section. How is the model going to be loaded, what is going to be used, IfcLoader or FragmentsManager. The ElementProperties, EntityAttributes, and ModelsList showed it, but the other tutorials didn’t.

const ifcLoader = components.get(OBC.IfcLoader);
await ifcLoader.setup();
const file = await fetch(
  "https://thatopen.github.io/engine_ui-components/resources/small.ifc",
);
const buffer = await file.arrayBuffer();
const typedArray = new Uint8Array(buffer);
const model = await ifcLoader.load(typedArray);
world.scene.three.add(model);

I think that is all I can say from my observation of UserInterface tutorials section.

Next is the language or term used in the tutorials. Aside from the object names mentioned above, there are a couple of noticeable inconsistencies with the labels used on the buttons. Downloads or Exports, again, may be subjective, and both do the same.

"Export" properties JSON and "Download" relations

But some labels, like Load IFC may mean to load an IFC file from your local PC or it may mean that an IFC file will be loaded asynchronously from a site or a server. Or it could be a fragment file and not an IFC. For the sake of those new to learning programming and new to ThatOpen documentation, what could this mean without looking at the coding? Well, we wouldn’t know until we tried a live example or read the code. There must be a clearer label that is easy to decipher and understand for the new learners of this library.

Load IFC or Load IFC from server or Load IFC from folder

On IfcGeometryTiler and IfcPropertiesTiler, Load IFC does the opposite, as it downloads a bunch of files to the local system of the user. Should that mean to say Export IFC processed geometry tiles and Export IFC processed property tiles or maybe something similar but shorter.

In another tutorial, AngleMeasurement, consistency in the colors used in the measurement lines. The usual red color lines become violet and are hard to see. All other measurement components use red lines except for others, like FaceMeasurement and VolumeMeasurement.

There is also the missing control panel, as well, so the user cannot control the color, and there are no help instructions in the UI visible similar to those featured in the LengthMeasurement. Which points me to the final observation and suggestion, consistency of UI panels featured for all measurement tutorials.

AngleMeasurement
AreaMeasurement
EdgeMeasurement
FaceMeasurement
VolumeMeasurement
MeasurementUtils

End...

Reproduction ▶️

https://people.thatopen.com/c/help-us-do-better/consistency-in-process-and-language-in-the-documentation

Steps to reproduce 🔢

Visit each Tutorial mentioned in the description.

System Info 💻

Windows 11
Google Chrome Version 127.0.6533.89 (Official Build) (64-bit)

Used Package Manager 📦

npm

Error Trace/Logs 📃

No response

Validations ✅

• Read the docs.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.
• Make sure this is a repository issue and not a framework-specific issue. For example, if it's a THREE.js related bug, it should likely be reported to mrdoob/threejs instead.
• Check that this is a concrete bug. For Q&A join our Community.
• The provided reproduction is a minimal reproducible example of the bug.