buildingSMART / buildingSMART/IFC4.x-development

Proposal to restructure superfluous property set descriptions.

Open
#419 1 comment 0 reactions 0 assignees View on GitHub
after-NWI allocated allocated-core iso-compatibility
Dominant language
Python
Stars
234
Forks
123
Avg merge
15h 4m
Merged PRs (30d)
5

Description

I've noticed that there are a number of superfluous property set descriptions. These add unnecessary maintenance and have no insights for a user. Evidence is in #402 #416 #417 #418.

In short, here's a _good_ example of a definition of a property set for Pset_ControllerTypeTwoPosition:

> Properties for signal handling for an analog controller taking disparate valued multiple inputs and creating a single valued binary output.

It's descriptive and adds value. Hooray!

But if I go to annex A and randomly click on a few here is what I get:

> Pset_AirTerminalOccurrence Air terminal occurrence attributes attached to an instance of [IfcAirTerminal](http://localhost:5000/IFC/RELEASE/IFC4x3/HTML/lexical/IfcAirTerminal.htm).
> Pset_BeamCommon Properties common to the definition of all occurrence and type objects of beam.
> Pset_AlarmPHistory Properties for history of alarm values.
> Pset_CargoCommon Properties common to the definition of all occurrences of [IfcTransportElement](http://localhost:5000/IFC/RELEASE/IFC4x3/HTML/lexical/IfcTransportElement.htm) and types of [IfcTransportElementType](http://localhost:5000/IFC/RELEASE/IFC4x3/HTML/lexical/IfcTransportElementType.htm) with the predefined type set to CARGO.
> Pset_CooledBeamPHistoryActive Performance history attributes for an active cooled beam.
> Pset_FlowMeterOccurrence Flow meter occurrence common attributes.
> Pset_TankOccurrence Properties that relate to a tank.
> Qto_CoolingTowerBaseQuantities Base quantities that are common to the definition of all types of cooling towers.
> Qto_RailBaseQuantities Base quantities that are common to the definition of all occurrences of rail.
> Qto_SiteBaseQuantities Base quantities that are common to the definition of all occurrences of site.
> Qto_TankBaseQuantities Base quantities that are common to the definition of all types of tanks.

Given that we now have much more modern document generation, the applicable entities and predefined types are clearly listed, I see no value in these types of sentences.

Proposal:

- Audix suffixes like Common, PHistory, BaseQuantities, and Occurrence for inconsistencies. e.g when should we use Common? Is Pset_ActionRequest or Pset_ActionRequestCommon correct? Pset_Asset or Pset_AssetCommon?
- Potentially use human translatable names for all property set names, property names, and enum names. They may be then converted into canonical form, but there will always be a human name that can be translated and displayed for users. A lot of the descriptions simply repeat the name.
- Delete any description which only repeats the name, applicability, and type (e.g. common, phistory, basequantities).

It may sound like a small thing, but I truly believe that portions of IFC are getting verbose which can give off the impression of a "monster" specification. I propose to remove these as part of a general strategy post deadline to make the docs less repetitive (DRY principle), improve hyperlinking to vital concepts, and [use clearer language](https://www.archives.gov/federal-register/write/legal-docs/clear-writing.html).

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.