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