[Ccsds-omg-liaison] Preliminary AB Review: Command and Control Message Specification (C2MS) 1.0 FTF report

[Elisa Kendall]

Hi all,

Here is my initial AB review of the C2MS 1.0 FTF report.

Document check:

Command and Control Message Specification (C2MS) 1.0 FTF report     dtc/19-05-01
Convenience document clean        dtc/19-05-02
Convenience document with change bars        dtc/19-05-03
Ancillary report attachments   dtc/19-05-04
C2MS XML Schemas dtc/19-05-05
C2MS XMI of the model file for UML model in the specification     dtc/19-05-06
SVG image archive  dtc/19-05-07
C2MS MagicDraw (.mdzip) for UML model        dtc/19-05-08

A. Report:  First, I want to say congratulations - this is a huge leap forward over the last version I saw, and I'm really glad that you took the feedback that Jason and I provided to heart.  Again, the voting record was clear, the report was well formed, and the issues were relatively clear. There were still some things that I would like to see fixed with respect to filing issues the next time you do this, such as the clause and section identified when an issue is raised should actually include the clause and section rather than 'n/a', although I found that for the most part in the resolutions.

With respect to how the issues were identified in the convenience document, we have conventions for that which are more pronounced and 'in your face' than what you did, but at least I could find things.  I'll provide an example of what we would like to see in your next revision in a follow-up message that doesn't clutter this one or copy everyone.  But given how much better this is than the prior version, I'm ok with what you did in the convenience document.  In general, it was an order of magnitude easier to compare your changes with the report indicating what was voted on, which was one of the primary concerns we had the last time around.

I still noticed two cases, C2MS-10 and C2MS-12 where revised text was indicated - included in the resolution summary, but then in the next section under "revised text", the report still says "n/a; will provide change bar version of word file".  Because the text changes were there in the resolution summary, I was able to review what was done, but please put all text changes, including: (1) precisely what is in the source document, and (2) precisely what you are changing it to, with the exact section and page number to which the change applies (including every instance of any change), in the section of the resolution called "revised text".  Note that changes to tables and figures are also considered revisions to the 'text' of the specification.  Things that are not revisions to text are essentially and only changes to machine readable files that have no corollary in the body of the document.

Again, what you've done is truly an improvement, and I had peeked at the resolutions for a couple of issues when you asked a few weeks ago, which were ok, but I'm finding others like these two, and cases where figures changed even if wording did not, that were not as meticulous.  I found the wording that you changed in the summary for those two issues and could correlate that with the convenience document, but we really need precise editing instructions, as if the person making the changes does not have the convenience document and is doing this as a technical editor blindly.  The changes need to be (1) summarized generally in the resolution summary, and (2) itemized very specifically and completely in the section called revised text, including figure replacements.  It has to be painfully clear as to what was voted on and what should be changed in the specification itself.  We know that's a lot of work, but for the standard to hold up with respect to international review, it's incredibly important.

In addition to C2MS-10 and C2MS-12,

(1) C2MS-17 should say "replace image x with image y" in each case where a figure was replaced due to color changes,

(2) The resolution to C2MS-19 should say "Replace the machine-readable XMI file with <filename> to correct the invalid version that included extraneous namespaces and nul character, with the file attached to this resolution."  and then attach it.

It currently reads, "This file is generated by MagicDraw
I will regenerate the file from the updated model version for other FTF 1.0 updates; but if it's still invalid
MagicDraw needs to get involved. If invalid, I will contact them and report the issue."

(3) The resolution to C2MS-20 says:

"Fixed in subsequent submission
Turns out we had a zip within a zip. Fixed now. Fixed at same time as issue 16"

and should say, "File <filename> contained a zip archive within a zip archive.  That has been corrected in the attached."  and, attach it, even if it is the same zip archive as the one you attached to issue 16.  Then the revised text should simply say 'n/a'.

(4) The resolution to C2MS-24 says:

"Command Echo message added
Draft originally from Rich Monteleone (RTLogic). Eric Ogren supported final development of new
message."

and should really summarize the change.  I note that you did attach the modified text and diagram in this case, which is good, but a summary of what you did in response to the resolution is really needed.

(5) The resolution to C2MS-25 says: "n/a; appears in diagram - see attachment to resolution" and should say "Replace figure 8-11 with the attached figure."

(6) The resolution to C2MS-36 says: "n/a; appears in diagram - see attachment to resolution" and should say "Replace figure 8-10, Device Message Diagram with the attached figure."  This case is really a problem, since there is no figure number, no page number and no paragraph number.

(7) The resolution to C2MS-57 says: "n/a; appears in diagram - see attachment - 3rd bubble from the bottom was fixed" and should say "Replace figure7-1, C2MS Message Exchange Patterns Diagram with the attached figure."

Cases such as C2MS-21, where at least in the resolution summary you have the table numbers, are slightly better, but the summary should be a summary with justification for the change and the actual text replaced, quoted precisely, with each table itemized, is what we think should really be done, more like what you did for C2MS-40 but for each table where there was a replacement even if it feels like busy work / duplication.  You did not need the same wording in both places - a summary in the summary section and the actual change in the revised text section. In general, your resolutions from C2MS-78 and above were better - at least the revisions were provided in attachments and the revised text said that and where they belonged.

Essentially, I think the convenience document (both redlined and clean) are ok, but I would like to see the report fixed and regenerated to address C2MS-10, C2MS-12, and the others listed in (1)-(7), above.

B. XMI FIle (dtc/19-05-06).  There are MagicDraw-specific elements in this that need to be removed - they appear in both the header and footer of the file.  Pete may be able to assist with that, since I don't want to mess it up.  I have an older version of MagicDraw that said the file was corrupted, but I think Pete has 18.5 and can check it.  I did upload it to the XMI validator which did not identify any issues.

C. Ancillary MagicDraw Model File (dtc/19-05-08).  This opened for me, even in the older version of MagicDraw, but I expected a model that included all of the diagrams, and I only saw a few - clearly there is another model that wasn't provided?  The idea is to include all of the model files needed to recreate the diagrams in the document.

Summary: I think this is far better than what you submitted in Reston.  But I would like to see (1) the items identified with respect to the resolutions corrected in the report, with no need for a new vote, (2) someone else check the XMI file to make sure it is ok aside from eliminating the MagicDraw specifics, so you'll need a new document number for that, which will change the report AND the cover of both convenience documents (meaning, that you'll need new document numbers for the report, convenience docs, and XMI file) and (3) whatever additional MagicDraw or other tool model files used to create the diagrams that are not in the one you uploaded need to be provided.  You could get one document number and add all of the MagicDraw .mdzip files to a single ancillary zip archive if that works for you, which will also need a new document number (which should be updated in the report, not needed on the cover of the document since it is ancillary).

Also note that all normative or informative machine readable documents need to be identified on the cover page and they are missing on both convenience docs, so please address that when you fix the XMI ... which is why I said that the convenience docs will need to be revised.  It's just to add the machine readable file references, but only for the XML schemas provided in dtc-19-05-05 and the XMI file.  There are lots of examples of how to do this, and Brad should be able to assist, since he's on your FTF :).

I think this is doable between now and the 6/17 AB meeting, and if you are able to do that and get someone else to assist with the XMI, you should be in good shape this time.  I did not check the XML schemas for validity - assuming that another AB member with the appropriate tools can do so.

You may want to pause on resubmitting new diagrams until you receive feedback from any other AB member - I think it is Larry's homework too, but you'll need help from Pete or Manfred or someone with respect to fixing and retesting the XMI.  Please let me know if you have any questions, and I look forward to seeing you in a little over a week,

Elisa
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.ccsds.org/pipermail/ccsds-omg-liaison/attachments/20190608/b3867581/attachment-0001.html>