Closed kgal closed 10 years ago
WeeknightMVP
commented
10 years ago http://www.plainlanguage.gov/howto/wordsuggestions/shallmust.cfm
On Tue, Jun 24, 2014 at 1:15 PM, kgal notifications@github.com wrote:
Closed #31 https://github.com/commoncriteria/application/issues/31.
— Reply to this email directly or view it on GitHub https://github.com/commoncriteria/application/issues/31#event-134656332.
Matt Benke
WeeknightMVP
commented
10 years ago Assurance Activity : SFR :: Work Unit : SAR
Work units are defined in the Common Evaluation Methodology, a companion document to the Common Criteria that stipulates how evaluators shall go about evaluating a given PP/ST against a given SAR. Modulo s/shall/must (because the previously established association of shall to sentient beings vs. "must" for inanimate objects has been muddied; otherwise it would have been consistent to use "must" for requirements for the inanimate TOE and "shall" for activities performed by stakeholders), I see no reason to use "will" to distinguish activities levied upon developers vs. evaluators -- they're simply distinct roles.
Another thought: All SFRs (except the derived FMT_SMF.1.1 that hasn't yet been refined accordingly) are of the form "The application must {...}.", and all assurance activities are of the form "The {developer|evaluator} must [or "will" for evaluators if Kevin gets his way] {...}." We have XML. We have XSLT. Why don't we just put these phrases straight into the stylesheet templates to ensure consistency of presentation?
On Tue, Jun 24, 2014 at 1:15 PM, kgal notifications@github.com wrote:
'shall' shall not be used. 'must' is used for requirements. 'will' is used to describe assurance activities, as this document explicitly levies requirements on applications and not evaluators. Evaluators should be thought of as automatons (things as opposed to people) so 'will' is more appropriate.
— Reply to this email directly or view it on GitHub https://github.com/commoncriteria/application/issues/31#issuecomment-47000705 .
Matt Benke
jeffblank
commented
10 years ago Kevin, you cannot change SAR text. If you do not see _EXT in the requirement title, then it is from the CC catalog (parts 2 or 3) and cannot be arbitrarily changed.
Everyone must (shall?) check with me in the future before engaging in any document-wide changes.
I am going to revert your commit.
Matt, XSL is not the fix for this. The authors need to be able to read it too, and should also become aware of some of the CC "rules".
WeeknightMVP
commented
10 years ago Okay I just reverted it.
This commit had one other change https://github.com/commoncriteria/application/commit/da15b8601ef2190f3127895f7d263f63977b4b6a#diff-f41ddbcdfc2e5dff08f40ced533afdb7L698: FMT_CFG_EXT.1.1; "configured by default" --> "initially configured"
Commentary to follow...
On Wed, Jun 25, 2014 at 11:18 AM, jeffblank notifications@github.com wrote:
Kevin, you cannot change SAR text. If you do not see _EXT in the requirement title, then it is from the CC catalog (parts 2 or 3) and cannot be arbitrarily changed.
Everyone must (shall?) check with me in the future before engaging in any document-wide changes.
I am going to revert your commit.
Matt, XSL is not the fix for this. The authors need to be able to read it too, and should also become aware of some of the CC "rules".
— Reply to this email directly or view it on GitHub https://github.com/commoncriteria/application/issues/31#issuecomment-47115770 .
Matt Benke
WeeknightMVP
commented
10 years ago Kevin, you cannot change SAR text. If you do not see _EXT in the requirement title, then it is from the CC catalog (parts 2 or 3) and cannot be arbitrarily changed.
So here's the issue:
Summarily, ISO/IEC standards could be interpreted to conflict with Plain Language legislation, on the grounds that "shall" is ambiguous. But "shall" is not ambiguous in this context; it is clearly defined in Annex H of the ISO/IEC Directives Part 2, which Common Criteria documentation cites as its basis. My recommendation is thus to rephrase our extended PP requirements in terms of "shall (not)", and recommendations in terms of "should (not)", as per this ISO/IEC directive. This is not only clear w.r.t. a ubiquitous and citable directive for specifying requirements, but is more consistent with Common Criteria and thus less likely to introduce conflicts with its formalisms.
Matt, XSL is not the fix for this. The authors need to be able to read it too, and should also become aware of some of the CC "rules".
A basic principle of development (be it of software, documentation, etc.) is DRY: Don't Repeat Yourself. I proposed XML markup with XSLT templates as a way to avoid repeating ourselves and ensure consistency of repetitive requirements of the form "{x} shall {y}.". An alternative is to quality-check for inconsistent alternatives (e.g. "must (not)", "may (not)", etc.), but this is less thorough (e.g. some joker uses the phrase "oughtn't"). I strongly agree that PP authors should learn the "CC rules", although slogging through the CC specification or getting slapped every time they break a rule are not the most efficient ways to achieve this...
On Wed, Jun 25, 2014 at 11:47 AM, Matt Benke matt.benke@gmail.com wrote:
Okay I just reverted it.
This commit had one other change https://github.com/commoncriteria/application/commit/da15b8601ef2190f3127895f7d263f63977b4b6a#diff-f41ddbcdfc2e5dff08f40ced533afdb7L698: FMT_CFG_EXT.1.1; "configured by default" --> "initially configured"
Commentary to follow...
On Wed, Jun 25, 2014 at 11:18 AM, jeffblank notifications@github.com wrote:
Kevin, you cannot change SAR text. If you do not see _EXT in the requirement title, then it is from the CC catalog (parts 2 or 3) and cannot be arbitrarily changed.
Everyone must (shall?) check with me in the future before engaging in any document-wide changes.
I am going to revert your commit.
Matt, XSL is not the fix for this. The authors need to be able to read it too, and should also become aware of some of the CC "rules".
— Reply to this email directly or view it on GitHub https://github.com/commoncriteria/application/issues/31#issuecomment-47115770 .
Matt Benke
Matt Benke
WeeknightMVP
commented
10 years ago I have not recommitted "configured by default" --> "initially configured"; while only one such substitution was made, there are four occurrences of "configured by default" and I'm not sure which occurrences warrant this change.
On Wed, Jun 25, 2014 at 11:47 AM, Matt Benke matt.benke@gmail.com wrote:
Okay I just reverted it.
This commit had one other change https://github.com/commoncriteria/application/commit/da15b8601ef2190f3127895f7d263f63977b4b6a#diff-f41ddbcdfc2e5dff08f40ced533afdb7L698: FMT_CFG_EXT.1.1; "configured by default" --> "initially configured"
Commentary to follow...
On Wed, Jun 25, 2014 at 11:18 AM, jeffblank notifications@github.com wrote:
Kevin, you cannot change SAR text. If you do not see _EXT in the requirement title, then it is from the CC catalog (parts 2 or 3) and cannot be arbitrarily changed.
Everyone must (shall?) check with me in the future before engaging in any document-wide changes.
I am going to revert your commit.
Matt, XSL is not the fix for this. The authors need to be able to read it too, and should also become aware of some of the CC "rules".
— Reply to this email directly or view it on GitHub https://github.com/commoncriteria/application/issues/31#issuecomment-47115770 .
Matt Benke
Matt Benke
kgal
commented
10 years ago Should someone change all the must s to shall s?
jeffblank
commented
10 years ago Done. I think.
'shall' shall not be used. 'must' is used for requirements. 'will' is used to describe assurance activities, as this document explicitly levies requirements on applications and not evaluators. Evaluators should be thought of as automatons (things as opposed to people) so 'will' is more appropriate.