General usability issues of docs

[aothms]

page rating idea

Suggestion courtesy of @timmcginley Should we have some really quick thumbs up thumbs down, or rate this page kind of thing, to get a more comprehensive view on gaps or quality issues that documentation writing should focus on? Something really accessible without a need for logging in, where creating an account and filing github issues would be too much of a barrier?

[Moult]

Yeah this is a great idea but I don't know the best way to implement this (permanent ratings? flagging mechanism? anonymous vs named reports?) I also reckon we can (and should) do a lot of preventative doc writing first :) Kinda like spend a few "edit-athons" just improving the wording, improving formatting, standardising the way we reference and providing examples, etc.

Because the perfect is the enemy of the good, I've put a link to this issue. If anyone is motivated, but not motivated enough to make the actual page edit as a pull request, please comment here and we'll see what happens. Worst case this was a bad idea and we revert, best case, we find poor documentation and fix it :)

[PedroRuda]

Hello to all the team of ifc4 3 documentation. Congratulations for your great job. The new interface is clearer than the previous one and the small windows linking to other concepts are extremely useful. I miss however some clarifications for main concepts in the page. Each of the headers describe some ifc main 'ideas' that would be great to clarify i.e 'Concept usage', which i haven't found the meaning explained in the documentation. Or a legend, explaining the colours used in the entity inheritance tree ( red for deprecated, grey for?) . Congrat again for the great job.

[aothms]

Hi, thanks, I think both are valid comments (wrt to explanation of terms used and wrt to general explanation of colours and symbols). Are you interested in helping out? Especially the inheritance listing legend would be a nice issue to get started, because they are pure html.

[PedroRuda]

Hi there Aothms for sure I can help. My knowledge in html is equal to 0 though... I understand that I can write some of the tooltips for the event ('on hover' ?) for each of the cases?

[aothms]

onhover is not necessary, in HTML it's sufficient to add a title attribute which gets displayed as a little tooltip on hover.

I was actually more thinking of printing the legend above or below the diagram, using similarly styled items and their meaning printed next to it.

[antunesml]

Industry Foundation Classes Data Architeture (Modification) Industry Foundation Classes (IFC) Architeture version 4.3.x overview (Figure 1) shows data squema layers where Core layer represent the root of tree. Interoperability and Domain layers are exposed to principle of inheritance, wich does not occur for Resource entities (8.x.x.x). So, i think the overview can not help to understand well it. Usually, the diagrams of architeture data are phylogenetic trees like graphical representations of evolutionary relanshionships and them are fundamentally important in modern taxonomy used in a wide variety of practical applications.

Figure 1. IFC Architeture version 4.3.x overview

Schramm T. et al. (2021) on their research say phylogenetic trees are important tools for understanding evolution, yet actors envolved on Projects are read and interpret them correctly. The researchs investigated 1197 diagrams focused on important aspects of evolutionary relanshonships and comparing results (Figure 2). The most of studies, root on left and below positions are the main way to representation hierachy of trees.

Figure 2. Root on diagrams

Resource entities on IFC schema are end-uses, so them support Core entities for all specification on schema. In this case, i suggest two triangles to represent IFC data. Kernel and extensions (Core layer) on the top of the smallest triangle, representing the base of the structure above, the big one (Interoperability and Domain layers). This condition clarifies about that resource entities do not inherit from Core layer. So, opposite way of all of others on IFC schema. Also, Core layer represents the conection (intersection) between the two triangles. In Figure 3, i demonstrated the equivalences and suggested the new overview.

Figure 3(a). Demonstration

Figure 3(b). New proposition

[HoKolo82]

There is a typo in property name FlowMeterOurpose (should be FlowMeterPurpose) on page https://standards.buildingsmart.org/IFC/RELEASE/IFC4_3/HTML/lexical/Pset_FlowMeterOccurrence.htm (I just followed the "Let us know" link).

[HoKolo82]

A very useful search field used to be available on the cover page (https://standards.buildingsmart.org/IFC/RELEASE/IFC4_3/), enabling fulltext search in the whole text content, but it has been recently removed for unknown reasons. Could it be brought back? It was the only way how to find anything without knowledge where exactly to look for it.

[aothms]

@HoKolo82 you're looking at the static HTML snapshot. The live version only has the search ifc43-docs.standards.buildingsmart.org

[asf-asf]

I followed the "Is this page difficult to understand? Let us know!" link on https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcCurveSegment.htm

I am having some trouble interpreting the statement

RefDirection is bound to the parametrization sense of the segment.

What does "bound to" mean here?

[ennetbadener]

Pls integrate in the official 4.3 Page the search Bar. similar in the dev Environement https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcRoot.htm

that makes ifc searching und using much easier.

[matgitbac]

https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcGeometricRepresentationContext.htm

“Use of representation contexts defined at IfcProject for 3D model and 2D plan context, including sub context definitions for different target scales. There shall always be a maximum of one geometric representation context for 2D and for 3D coordinate space.”

My interpretations of this is, that it is allowed that only two IfcGeometricRepresentationContext instances, specifically one 3D and one 2D coordinate spaces can be defined.

However, in the blogpost https://thinkmoult.com/ifc-coordinate-reference-systems-and-revit.html Dion Moult suggests "I would like to emphasize that the inheritance of coordinate transformation is not done due to spatial containment, but instead due to the selection of IfcRepresentationContext. This allows different IfcSite elements to have a different IfcRepresentationContext, and therefore have a different MapConversion. This is useful if you are working on a small town or any geographically large projects, as different sites will likely require different Helmert transformations. That said, I have heard talk that the IfcMapConversion could be moved to be defined at the IfcSite level, instead of the IfcProject.“

We are trying to achieve exactly this, to use different helmert transformations to position multiple “subsites” at a large railway infrastructure site. Is there a contradiction or do I interpret the IFC4x3 documentation incorrectly? If it is allowed to define multiple IFCRepresentationContexts to define multiple associated IFCMapConversions? Further down with “HasCoordinateOperation” I get the impression that more than two (2D and 3D) IfcGeometricRepresenationContexts are allowed “If there is more then one IfcGeometricRepresentationContext provided to the IfcProject then all contexts shall have an identical instance of IfcCoordinateOperation as HasCoordinateOperation referring to the same instance of IfcCoordinateReferenceSystem.“

If multiple IfcGeometricRepresentationContexts are allowed and can be used to define multiple helmert transformations (same Project CRS), what is the common approach to implement this? Maybe you could suggest some examples with real data?

cheers

[aothms]

@matgitbac

If multiple IfcGeometricRepresentationContexts are allowed and can be used to define multiple helmert transformations (same Project CRS), what is the common approach to implement this? Maybe you could suggest some examples with real data?

No I don't think this is allowed. After Implementer feedback, this has been further specified in the rule https://github.com/buildingSMART/ifc-gherkin-rules/blob/main/features/GRF001_Identical-coordinate-operations.feature

A bit analogous to the schema rule https://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcRepresentationContextSameWCS.htm which is the same idea I'd say, but then from a CAD perspective.

I think the best place to get some closure on this is discussing this in the Implementer Forum https://github.com/buildingSMART/IFC4.x-IF/issues

[Moult]

Yes - that blog post is outdated and at the time it was a theoretical possibility but as mentioned it's basically a really bad idea to mix any sort of multiple coordinate transformations in a single dataset. The next paragraph in the blog post clarifies that it's a terrible idea :)

I've fixed the blog post.

[matgitbac]

Thanks @aothms and @Moult for your responses. I'll post my question how to implement it best in the Implementer forum

[nickger]

Hello, Is there a way to understand to which schema and domain belongs a class? Looks like these "schamas" and "domains" are not presented in the format, though are extremely usefull. Second question: why obsolete (according to documentation) attributes have no such info in xsd schema description? I believe it is essential to provide this information, so no one will rely on obsolete parameters.

[lbaiao]

Hi. Can we add the sub-topics to the left panel, nested under the respective topics? This would really improve UX and readability.