Clarification of GTFS Realtime occupancy descriptions

[sccmcca]

Following the conversation in #212, this pull request aims to disambiguate the intended use of OccupancyStatus as describing the nominal status of passenger occupancy levels, and occupancy_percentage as describing passenger occupancy levels on a linear scale.

Summary:

• Clarification to OccupancyStatus as indicating the nominal status of passenger occupancy; removal of "percentage" language to avoid confusion with occupancy_percentage.
• Editorial clarification of occupancy percentage description.
• Added line breaks to Caution statements for improved legibility.

Feedback is welcomed.

[stevenmwhite]

These changes are helpful, particularly with the added details.

[skinkie]

+1 OpenGeo

[abyrd]

It does seem like a good idea to replace the word "percentage" on fields that do not actually contain percentages. However, this PR replaces "percentage" with "allocation", which implies that someone allocated the seats, i.e. someone assigned them to a specific person or usage. The new word seems less clear than the one it replaces.

It also replaces the expression "degree of passenger occupancy" with "nominal state of passenger occupancy". I think I understand the intended meaning here, that this is a "name for the occupancy state" rather than a quantitative measure, but I suspect most readers will perceive it as opaque jargon. In common usage "nominal" means something exists in name only, has characteristics different than those implied by its name, or is very small. In economics it might also mean something like "unadjusted", and in engineering something like "within acceptable range".

[sccmcca]

@abyrd Good points.

Perhaps we can replace "allocation" with "number" and "amount" such that the spec reads:

The vehicle or carriage has a large allocation number of seats available. The allocation amount of free seats out of the total seats available to be considered large enough to fall into this category is determined at the discretion of the producer.

As for "nominal", perhaps we can remove it and simply rely on the word "state" such that the spec reads:

The nominal state of passenger occupancy for the vehicle or carriage.

Thoughts?

[sccmcca]

Hi everyone,

It seems like we've settled on the final proposal. As the proposal concerns an editorial clarification to a historical feature, I believe we can assume implementation from at least one GTFS-realtime producer and consumer. Also, we are well past the required 7-day discussion period as outlined in the specification amendment process. Feel free to voice any remaining feedback. To be clear, this proposal is not suggesting to make official the experimental OccupanyStatus field. Rather, it is seeking editorial clarification.

Formally, I'm calling for a vote on the official adoption of the editorial changes proposed in this PR. The vote will close on 2021-01-29 at 23:59:59 UTC.

[skinkie]

+1 OpenGeo

[gcamp]

+1 Transit

[stevenmwhite]

+1 GMV Sync

[sccmcca]

The vote ended on 2021-01-29 23:59:59 UTC with a unanimous consensus of 3 yes votes from OpenGeo (@skinkie), Transit (@gcamp), and GMV Sync (@stevenmwhite). As per the specification amendment process, this proposal is accepted! Thanks to everyone involved.