buildingSMART / buildingSMART/IFC4.x-development
Proposal to restructure superfluous property set descriptions.
- 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
Assessment
This issue has not been assessed yet.