Proposal: [272] Relax documentation requirements of Ambiguous Conditions
This page is dedicated to discussing this specific proposal
ContributeContributions
JohanKotlinski
[272] Relax documentation requirements of Ambiguous ConditionsProposal2022-12-29 19:25:35
Author:
Johan Kotlinski
Change Log:
2022-12-29: Initial proposal
Problem:
Documenting all ambiguous conditions of a system can be burdensome for system implementers, while providing relatively little value to end-users.
Solution:
Relax the 4.1.2 wording from "A system shall" to "A system should". In that way, partial or complete absence of this documentation will not make a system non-standard.
Proposal:
In section 4.1.2 Ambiguous Conditions, change "A system shall" to "A system should".
Reference implementation:
N/A
znmeb
"Documenting all ambiguous conditions of a system can be burdensome for system implementers, while providing relatively little value to end-users."
As an end user, I want the documentation for all ambiguous conditions. I don't want to have to discover them while creating an application, then go to a support site, or, worse yet, have to read the source, for which I may not even have a license!
JohanKotlinski
znmeb, thank you for your feedback. Out of curiosity, could you give some example documentation of ambiguous conditions that you like to use?
ruv
znmeb writes:
As an end user, I want the documentation for all ambiguous conditions.
Do you think that less systems will provide this documentation if this documentation will no longer be required (but only recommended) for a standard system?
znmeb writes:
I don't want to have to discover them while creating an application
Just take into account that if your application relies on some specific behavior in an ambiguous condition, then your application has an environmental dependency.
See Chapter 3: "A program that requires a system to provide words or techniques not defined in this standard has an environmental dependency". So, if a program requires a system to have some specific capability beyond minimal, or behavior, which is not defined by the standard, then this program has an environmental dependency.
A standard program without environmental dependencies does not need to know what is the system behavior in any ambiguous condition.
OTOH, to choose a system for use in production you probably need to know what is the system behavior in certain cases. For example, how to handle a case of "addressing a region not listed in 3.3.3 Data space" (including a case when the address is not mapped to physical memory at all).
If a system does not provide the documentation for a specific behavior or feature that a program requires, then this system just does not formally meet the environmental dependencies of the program. Why should it make the system non standard?
AntonErtl
We discussed this issue at the meeting on 2023-02-17. We decided to proceed this proposal to CfV status, in order to hear more feedback from the wider community once the voting actually works.
The issue at hand is: Has the information in your favourite Forth system's documentation about ambiguous conditions really ever been of use to you, or is it just busywork for system implementors?