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

Mon Dec 4 12:50:37 UTC 2023

Regarding the option to move section 3 in its entirety to a Magenta book.

I don't agree that we can move the Data Structure tables to a Magenta book.
The service specification requires the definition of its data structures.
They are also needed to generate the XML Specification.

In other books the Services are defined in section 3 and the data structures
in section 4.  We could follow that approach, with just the tables and
associated descriptive text that is used in the XML.
The Magenta book could essentially be a copy of section 3.  If we include
the data structure tables in the Magenta book, then we have
repetition/consistency issue.  I would replace them with something less
formal (no SFP, no nullability, simplified type, but keep the description).

From: MOIMS-MP <moims-mp-bounces at mailman.ccsds.org> On Behalf Of Peter Van
Der Plas via MOIMS-MP
Sent: Monday, December 4, 2023 12:10 PM
To: moims-mp at mailman.ccsds.org
Cc: Daniel Fischer <Daniel.Fischer at esa.int>
Subject: [Moims-mp] FW: Additional "editor's note" on our MP&S Blue Book

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
 <mailto:Peter.van.der.Plas at esa.int> Peter.van.der.Plas at esa.int |
<http://www.esa.int/> 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
<mailto: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
 <mailto:Peter.van.der.Plas at esa.int> Peter.van.der.Plas at esa.int |
<http://www.esa.int/> 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
 <mailto:Peter.van.der.Plas at esa.int> Peter.van.der.Plas at esa.int |
<http://www.esa.int/> 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 <mailto:dpo at esa.int> ). 
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mailman.ccsds.org/pipermail/moims-mp/attachments/20231204/20978427/attachment-0001.htm>