The format of concepts is not done consistently throughout the spec document.
Here are a few instances to illustrate the inconsistency.
The verb "Completed" is capitalized but not quoted here.
e.g.
line 833 The AU SHOULD NOT set a progress value in a Completed statement
The verbs "Terminated" and "Initialized" are both capitalized and quoted here, however the ResultExtension "Duration" occurs in two places -- once it is quoted but not capitalized, once it is neither capitalized nor quoted.
e.g
Line 811 The AU MUST include the "duration" property in "Terminated" statements. The AU SHOULD calculate duration for Terminated statements as the time difference between the "Initialized" statement and the "Terminated" statement. The AU MAY use other methods to calculate the duration based on criteria determined by the AU.
The "Waived" verb is formatted differently in different places in the document
It is capitalized and quoted here
e.g.
line 846
LMS Usage:
The LMS MUST set this value in statements it makes with the verb "Waived". The value SHOULD be one of the following -
It is not quoted here
e.g.
line 856
LMS Obligation:
This is a required extension for LMS statements that include the Waived verb.
Once the format is determined regarding the capitalization and quoting of xAPI Profile concepts then the spec should be checked to ensure all concepts follow that convention.
The decision was made to add a section '1.2 How to read this document' which has the style conventions used in the document to format the cmi5 Profile concepts when referring to them in a variety usages such as when referent to statements
Following is the text developed at the January 27th, 2023 meeting
References to Statements
This document uses, as shorthand, specific vocabulary such as verbs in conjunction with the word "statement" (e.g., a "completed" statement). This shorthand refers to that statement meeting all requirements that would accompany the correct use of that concept. When using this shorthand with the word “the”, this means the cmi5 defined version of that statement with the verb’s display property. (see Section 7.1.3 Types of Statements for the definition of cmi5 defined)
For example:
The “completed” statement
Would be a cmi5 defined xAPI statement with a verb display name of ‘completed’ and a verb IRI of ‘http://adlnet.gov/expapi/verbs/completed’. Similar conventions might be used for other xAPI properties.
This document uses the following style conventions:
Back Ticks ( ` ) – (possibly rendered as “inline code”) for all literal names of verbs and properties – ‘completed’ verb
Double Quotes for shorthand – “completed” statement (as described in above)
Literal syntax case – When referring to verbs and properties the case will show as they appear in xAPI statements
Section Titles with verbs/properties – may use either Capitalized or Literal
Style Usage examples
the ‘score’ property
for ‘score’ when….
Remove bold/italic styling on verb & properties in text descriptions (use back ticks instead)
The ‘fetch’ parameter contains a URL value that is used to….
The “fetch” URL = The shorthand Concept of
The ‘fetch’ query parameter contains a URL value (the “fetch” URL) that is used by the AU to obtain an authorization token created and managed by the LMS. The authorization token is used by the AU being launched.
I have written a section 1.2 Document Style Conventions and submitted a pull request for your comments and edits.
I have not started on updating the content of the spec according to the guidelines
I don't think I will be able to attend the meeting today, Feb 17, 2023 nor next week, Feb 24, 2023 due to work. I will look at the repository for any code changes you made or at the minutes to see what changes you are recommending and then I will continue to work on the rest of the document from there.
The format of concepts is not done consistently throughout the spec document.
Here are a few instances to illustrate the inconsistency.
The verb "Completed" is capitalized but not quoted here. e.g. line 833 The AU SHOULD NOT set a progress value in a Completed statement
The verbs "Terminated" and "Initialized" are both capitalized and quoted here, however the ResultExtension "Duration" occurs in two places -- once it is quoted but not capitalized, once it is neither capitalized nor quoted. e.g Line 811 The AU MUST include the "duration" property in "Terminated" statements. The AU SHOULD calculate duration for Terminated statements as the time difference between the "Initialized" statement and the "Terminated" statement. The AU MAY use other methods to calculate the duration based on criteria determined by the AU.
The "Waived" verb is formatted differently in different places in the document
line 856
Once the format is determined regarding the capitalization and quoting of xAPI Profile concepts then the spec should be checked to ensure all concepts follow that convention.
This issue was discussed at the cmi5 working group meetings:
The decision was made to add a section '1.2 How to read this document' which has the style conventions used in the document to format the cmi5 Profile concepts when referring to them in a variety usages such as when referent to statements
Following is the text developed at the January 27th, 2023 meeting
I have written a section 1.2 Document Style Conventions and submitted a pull request for your comments and edits.
I have not started on updating the content of the spec according to the guidelines
I don't think I will be able to attend the meeting today, Feb 17, 2023 nor next week, Feb 24, 2023 due to work. I will look at the repository for any code changes you made or at the minutes to see what changes you are recommending and then I will continue to work on the rest of the document from there.