[Moims-mp] FW: Additional "editor's note" on our MP&S Blue Book

Mon Dec 4 12:09:50 UTC 2023

Dear all,

For the upcoming WG discussions on Wednesday, please find below some elaborations from Roger and me on how we could proceed regarding the feedback provided by the CCSDS Chief Editor on our Blue Book structure and contents.

Regards,

Peter

ESA - European Space Agency

Peter van der Plas
EGSE and Ground Systems section (TEC-SWG)
Directorate of Technology, Engineering and Quality

ESTEC
Keplerlaan 1, PO Box 299, NL-2200 AG Noordwijk, The Netherlands
Peter.van.der.Plas at esa.int<mailto:Peter.van.der.Plas at esa.int> | www.esa.int<http://www.esa.int/>
Phone +31 71 565 5848 | Fax +31 71 565 5420 | Mobile +31 6 81 75 01 50

From: Peter Van Der Plas
Sent: Monday, December 4, 2023 1:05 PM
To: roger.rocketbrain at btinternet.com
Subject: RE: Additional "editor's note" on our MP&S Blue Book

Hi Roger,

There is an option 4: to move the entire Information Model to a Magenta book. In this Magenta book there will then be the section 2 (IM part only) and the section 3.

The current Blue Book would then only describe the services, and in section 2 refer to the main data types used directly in the services.

In my understanding, a Magenta book will not require any prototyping. Not sure if in a Magenta book the UML diagrams could remain embedded with the tables. If so, then we could simply copy and paste the section 3.

Regards,

Peter

ESA - European Space Agency

Peter van der Plas
EGSE and Ground Systems section (TEC-SWG)
Directorate of Technology, Engineering and Quality

ESTEC
Keplerlaan 1, PO Box 299, NL-2200 AG Noordwijk, The Netherlands
Peter.van.der.Plas at esa.int<mailto:Peter.van.der.Plas at esa.int> | www.esa.int<http://www.esa.int/>
Phone +31 71 565 5848 | Fax +31 71 565 5420 | Mobile +31 6 81 75 01 50

From: roger.rocketbrain at btinternet.com<mailto:roger.rocketbrain at btinternet.com> <roger.rocketbrain at btinternet.com<mailto:roger.rocketbrain at btinternet.com>>
Sent: Monday, December 4, 2023 12:48 PM
To: Peter Van Der Plas <Peter.van.der.Plas at esa.int<mailto:Peter.van.der.Plas at esa.int>>
Subject: RE: Additional "editor's note" on our MP&S Blue Book

Hi Peter,

The fact that we have non-normative text and UML diagrams mixed with normative data structure tables is probably a violation of the publications manual.
However, Tom's comments are factually incorrect.  Section 3 does not just contain "a handful of requirements" - it contains the data specification tables that are normative and probably account for the majority of the 129 pages, so it cannot be removed in its entirety.  It is these tables that generate the bulk of the XML Service Specification.

The problem we have is that the UML is non-normative and if we were to move it to section 2, it would not be self-standing without duplicating much of the information that is contained in the normative data structure tables.

If we were to move the UML into section 2, it would not then be self-describing.  We don't want to add a lot of descriptive text there that duplicates what is contained in the data structure tables.

I see three options:

  1.  Fight to keep it as it is, possibly moving some of the more descriptive sections into section 2.  I don't see why we can't have UML diagrams to assist in understanding the data structures - but section 3.4 and introductory parts of 3.2 and 3.3 could be moved into section 2 as they are non-normative.
  2.  Do as in 1) for general parts of the Information Model section, but move the UML diagrams and associated description into an Annexe in the Blue Book (as well as the text from section 2 introducing Class and State diagrams), leaving only the Data Structure tables and associated descriptive text.
  3.  Move the UML with descriptive text that to some extent duplicates the data structure tables into a Magenta book, leaving only the Data Structure tables together with the associated descriptive text that is taken into the XML Specification.

From: Peter Van Der Plas <Peter.van.der.Plas at esa.int<mailto:Peter.van.der.Plas at esa.int>>
Sent: Friday, December 1, 2023 3:57 PM
To: roger.rocketbrain at btinternet.com<mailto:roger.rocketbrain at btinternet.com>
Subject: Additional "editor's note" on our MP&S Blue Book

Hi Roger,

I just got another email from Tom with the results of the CESG poll and the comments from Peter so far.

But then there was an additional "editor's note", see below. This seems to be a more fundamental issue.

We can discuss this in the meeting on Wednesday.

Cheers,

Peter

* * * * * * * * * * * * * * * * * * * * * * * * Editor's note:

Section 3 of this document, which is 129 pages in length and thus constitutes nearly half the document, is essentially a tutorial with a handful for requirements sprinkled in. It is as such in direct violation of the both the letter and spirit of the Publications Manual:

"terse style:  Style of specification in which normal text is limited to concise statements of requirements.  Discussions concerning rationale, background, and other ancillary topics are constrained to be brief and are set off from normal text, usually in a note, or sometimes in a subsection that is clearly labeled as being non-normative." (1.6.1                TERMS)

"3.4.3.3 For normative-track documents,

a)            specifications shall begin in section 3 and continue through as many subsequent sections as needed;

b)            each specification shall be explicitly identified by a unique subsection or paragraph number;

c)            text shall be written in terse style [emphasis added]; . . ."

Since there is no provision in CCSDS procedures for granting dispensations for Publications Manual requirements, section 3 needs to be either removed from the document in its entirety, perhaps to be reworked as a Magenta Book, or reduced to the handful of requirements it contains, possibly with the informative material replicated in a Green Book.

ESA - European Space Agency

Peter van der Plas
EGSE and Ground Systems section (TEC-SWG)
Directorate of Technology, Engineering and Quality

ESTEC
Keplerlaan 1, PO Box 299, NL-2200 AG Noordwijk, The Netherlands
Peter.van.der.Plas at esa.int<mailto:Peter.van.der.Plas at esa.int> | www.esa.int<http://www.esa.int/>
Phone +31 71 565 5848 | Fax +31 71 565 5420 | Mobile +31 6 81 75 01 50

This message is intended only for the recipient(s) named above. It may contain proprietary information and/or protected content. Any unauthorised disclosure, use, retention or dissemination is prohibited. If you have received this e-mail in error, please notify the sender immediately. ESA applies appropriate organisational measures to protect personal data, in case of data privacy queries, please contact the ESA Data Protection Officer (dpo at esa.int<mailto:dpo at esa.int>).
This message is intended only for the recipient(s) named above. It may contain proprietary information and/or protected content. Any unauthorised disclosure, use, retention or dissemination is prohibited. If you have received this e-mail in error, please notify the sender immediately. ESA applies appropriate organisational measures to protect personal data, in case of data privacy queries, please contact the ESA Data Protection Officer (dpo at esa.int).
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.ccsds.org/pipermail/moims-mp/attachments/20231204/25433667/attachment-0001.htm>