adlnet/xAPI-Spec — pull request #51 by paul-esch (2013-02-05 20:31:41+00:00)
Title: a bit of restructuring for 4.1.10 Voided

The meeting minutes of the workgroup meeting that took place 2 weeks ago call for a tech writer; I volunteer to be that writer.

My general idea is to add so-called Rationales to sections of the spec that explain the general idea of given section to both technical developers as other (non-technical) readers. Other info can be split down into Descriptions, Examples, Details, etc. Also, in many places clarity can be increased by logically grouping together requirements for the LRS, the LAP, the reporting system, etc. Sometimes small changes in words can also help to minimize possible ambiguity.

Regarding this particular commit:

As in my previous merges, I restructured the section 4.1.10 for added clarity.
Please check for completeness and correctness. Note that I changed
'should' into 'must' in the original sentence that read: 'should mark
the target statement as voided using the "voided" field.' (line 1226)

imho the method used for a core functionality such as voiding cannot be left to the developer's creativity. By all means,change back to SHOULD if MUST is too stringent; I did not follow all discussion around this in the past and there may be good reasons for SHOULD in the original line 1226.