recommended practice (magenta book) job aids toolkit/job aids... · web viewrecommended practice...

21
Author’s Toolkit Recommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document- development compliance guidance for Magenta Book authors and editors. This aid includes mandatory sections, boilerplate text, and general editorial “Did I/we do that?” assessments to make before sending in a document to the CCSDS document editors. The guidelines provided here have been compiled from the CCSDS Publications Manual (A20.0-Y-3 ), the April 2013 Technical Editor Boot Camp slides , the Magenta Book template , and the Organization and Processes for the Consultative Committee for Space Data Systems (A02.1.Y-3 ). For additional information, please refer to those documents. Hyperlinks to boilerplate text and further instructions are provided throughout this aid. Text in Times New Roman font indicates verbatim text extracted from the Publications Manual. If needed, users may copy/paste the boilerplate text into their documents 1 . An abbreviated, two-page compliance checklist is provided at the end of this document, as is a graphic that overviews the document- development process for both Blue and Magenta Books. Before You Start Pull the latest Magenta Book template from the Collaborative Work Environment (CWE). Using the correct template will better ensure compliance with the Publications Manual. Please try to stick to the pre-set styles in the template. 1 If you have difficulty pasting the text and getting it to look right, you may want to opt for using the "Paste Special" feature to paste the text as unformatted. Magenta Book Job Aid July 2013

Upload: phungtruc

Post on 11-Jul-2018

221 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: Recommended Practice (Magenta Book) Job Aids Toolkit/Job Aids... · Web viewRecommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document-development

Author’s Toolkit

Recommended Practice (Magenta Book) Job AidThis job aid and checklist consolidates all required document-development compliance guidance for

Magenta Book authors and editors. This aid includes mandatory sections, boilerplate text, and general editorial “Did I/we do that?” assessments to make before sending in a document to the CCSDS document editors. The guidelines provided here have been compiled from the CCSDS Publications Manual (A20.0-Y-3), the April 2013 Technical Editor Boot Camp slides, the Magenta Book template, and the Organization and Processes for the Consultative Committee for Space Data Systems (A02.1.Y-3). For additional information, please refer to those documents.

Hyperlinks to boilerplate text and further instructions are provided throughout this aid. Text in Times New Roman font indicates verbatim text extracted from the Publications Manual. If needed, users may copy/paste the boilerplate text into their documents1.

An abbreviated, two-page compliance checklist is provided at the end of this document, as is a graphic that overviews the document-development process for both Blue and Magenta Books.

Before You StartPull the latest Magenta Book template from the Collaborative Work Environment (CWE). Using the correct template will better ensure compliance with the Publications Manual. Please try to stick to the pre-set styles in the template.

Mandatory Book ContentsTitle Page2

NOTE: All CCSDS book templates include placeholders for the Title Page items listed below.

CCSDS Logo (included on the template)Series Name

White Book: Proposed Draft Recommendation for Space Data System PracticesRed Book: Draft Recommendation for Space Data System PracticesMagenta Book: Recommendation for Space Data System Practices

Title (The title must concisely identify the subject of the document.)Document Type

White Book: Proposed Draft Recommended Practice

1 If you have difficulty pasting the text and getting it to look right, you may want to opt for using the "Paste Special" feature to paste the text as unformatted.2 Technically, the CCSDS document editor is “responsible for the preparation of the CCSDS document front cover and front matter” of CCSDS books; nonetheless, the guidance is provided here for those authors who wish to be as autonomous and compliant as possible before submitting their work to the document editor for processing.

Magenta Book Job Aid July 2013

Page 2: Recommended Practice (Magenta Book) Job Aids Toolkit/Job Aids... · Web viewRecommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document-development

Author’s ToolkitRed Book: Proposed Recommended PracticeMagenta Book: Recommended Practice

Document Number: The format is CCSDS {number}-{letter}-{issue}NOTE: The {number} is supplied by the CCSDS Secretariat.Book Color: WHITE BOOK or RED BOOK or MAGENTA BOOKIssue Date: Must be in Mmmm-YYYY format (e.g., July 2013)

Front MatterNOTE: Hyperlinks to additional instructions and/or boilerplate wording are in blue underline.

Dedication page (used only on instruction from CCSDS Management Council)Authority pageStatement of Intent pageForeword (includes the Agency list)Preface Required for White and Red Books only.3 Document Control (history of the published issues of the document)Table of Contents: includes a) main section headings and level-two subordinate headings; b) annex main headings; c) index (if applicable), d) figures; and e) tables

Section 1: IntroductionThe introduction of the document shall identify and define the document, present conventions used in and definitions specific to the document, and provide a list of referenced documents. The introduction shall contain some or all of the following subsections in the given order. [emphasis added]

NOTE – Not all subsections are required for a given document.

Purpose: Required. […] identif[ies] the purpose of the documentScope: Required. […] define[s] the area to which [the document] appliesApplicability: Required. […] define[s] the implementations to which the document appliesRationale: Recommended. […] outline[s] the reasons the book, or a new issue, was publishedDocument Structure: Recommended. […] outline[s] the structure of the document and briefly identifies the contents of each section and annexDefinitions

Terms (if needed)Nomenclature: Required. If a Terms subsection is included, Nomenclature goes as a subsection to Terms; otherwise, it can stand as its own subsection under Definitions.Conventions (if needed)

References (if needed): Required in section 1 if publications are referenced directly in the text of the document.

3 Per the Publications Manual (see 3.3.6.5): A preface is not normally included in final publications but may be included to provide issue-specific information.

Magenta Book Job Aid Page 2 of 13 July 2013

May be merged together into a “Purpose and Scope” subsection

Page 3: Recommended Practice (Magenta Book) Job Aids Toolkit/Job Aids... · Web viewRecommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document-development

Author’s Toolkit

Section 2: OverviewThe overview section shall contain general text on the subject of the document. Sufficient text and/or tables and figures should be used to provide the reader with a clear understanding of the scope of the technical content of the book within the overall system.

No requirements or specifications shall be contained in the overview section.

Sections 3–n: Document Main Text (a.k.a. Technical Specifications)The main text for the document may be spread over many sections and subsections:

Each section of the document shall be devoted to a particular division of the subject.Specifications shall begin in section 3 and continue through as many subsequent sections as needed.Each specification shall be explicitly identified by a unique subsection or paragraph number.Text shall be written in terse style.Comments and explanatory material shall be clearly identified as non-normative:

the NOTE format [see 4.3.2.2 of the Publications Manual] shall be used for brief non-normative comments;non-normative text requiring one or more paragraphs of text shall be set off in special subsections having one of the following reserved titles:– Overview;– Background;– Rationale;– Discussion;descriptive text shall not introduce implicit or hidden requirements, or modify the meaning or obligations of existing requirements;normative text shall not appear in subsections whose titles are identified as reserved (Overview, Background, Rationale, Discussion)

NOTE – In general, non-normative text is to be avoided in normative sections (sections 3 through n) of CCSDS normative-track documents. CCSDS Informational Reports (Green Books) are the proper repository of non-normative text intended to aid in understanding or acceptance of normative-track documents.

Back Matter (Annexes)Normative annexes (as many as needed)

Normative annexes contain technical information which, because of its length, detail, or specificity, is inappropriate for inclusion in the main sections, but which is necessary for implementation of the specifications in the document.

Informative annexes (as many as needed)

Security, SANA, and Patent Considerations: Required. Per the April 2013 Technical Editor Boot Camp, a Magenta book must at least address “Security Considerations”.

Definitions and Terms

Index (if needed)

Magenta Book Job Aid Page 3 of 13 July 2013

Page 4: Recommended Practice (Magenta Book) Job Aids Toolkit/Job Aids... · Web viewRecommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document-development

Author’s Toolkit

Detailed Instructions and Boilerplate TextFront Matter ParticularsAuthority Page

The Authority page must include the following:

the Authority text box (see sample below); the box includes the Issue, Date, and Location;

NOTE: On the “Issue” line, the author may include either the book color (e.g., “Red Book”) or the document type (e.g., “Draft Recommended Practice”) followed by the Issue number.

the Statement of Authorization (boilerplate text below);

the address of the CCSDS Secretariat (boilerplate text below).

Sample Authority Text Box

Issue: Red Book, Issue n

Date: July 2013

Location: Washington, DC, USA

Statement of Authorization Boilerplate Text

The Magenta Book template includes the verbatim wording shown below as well as the correct spacing/ format. The parenthetical statement in the beginning must be included for White and Red Books; it will be removed upon the document’s change to Magenta Book status.

(WHEN THIS RECOMMENDED PRACTICE IS FINALIZED, IT WILL CONTAIN THE FOLLOWING STATEMENT OF AUTHORITY:)

This document has been approved for publication by the Management Council of the Consultative Committee for Space Data Systems (CCSDS) and represents the consensus technical agreement of the participating CCSDS Member Agencies. The procedure for review and authorization of CCSDS documents is detailed in Organization and Processes for the Consultative Committee for Space Data Systems (CCSDS A02.1-Y-3), and the record of Agency participation in the authorization of this document can be obtained from the CCSDS Secretariat at the address below.

This document is published and maintained by:

CCSDS SecretariatSpace Communications and Navigation Office, 7L70Space Operations Mission DirectorateNASA HeadquartersWashington, DC 20546-0001, USA

Magenta Book Job Aid Page 4 of 13 July 2013

Page 5: Recommended Practice (Magenta Book) Job Aids Toolkit/Job Aids... · Web viewRecommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document-development

Author’s Toolkit

Statement of Intent Boilerplate Text

The text below is not included in the Magenta Book template, as it is not applicable to the book when it is in its White and Red Book stages. It is provided here for informational purposes only.

Per section 3.3.4 of the Publications Manual: The exact text of the Statement of Intent is4:

The Consultative Committee for Space Data Systems (CCSDS) is an organization officially established by the management of its members. The Committee meets periodically to address data systems problems that are common to all participants, and to formulate sound technical solutions to these problems. Inasmuch as participation in the CCSDS is completely voluntary, the results of Committee actions are termed Recommendations and are not in themselves considered binding on any Agency.

CCSDS Recommendations take two forms: Recommended Standards that are prescriptive and are the formal vehicles by which CCSDS Agencies create the standards that specify how elements of their space mission support infrastructure shall operate and interoperate with others; and Recommended Practices that are more descriptive in nature and are intended to provide general guidance about how to approach a particular problem associated with space mission support. This Recommended Practice is issued by, and represents the consensus of, the CCSDS members. Endorsement of this Recommended Practice is entirely voluntary and does not imply a commitment by any Agency or organization to implement its recommendations in a prescriptive sense.

No later than three years from its date of issuance, this Recommended Practice will be reviewed by the CCSDS to determine whether it should: (1) remain in effect without change; (2) be changed to reflect the impact of new technologies, new requirements, or new directions; or (3) be retired or canceled.

In those instances when a new version of a Recommended Practice is issued, existing CCSDS-related member Practices and implementations are not negated or deemed to be non-CCSDS compatible. It is the responsibility of each member to determine when such Practices or implementations are to be modified. Each member is, however, strongly encouraged to direct planning for its new Practices and implementations towards the later version of the Recommended Practice.

Foreword

The Magenta Book template provides the boilerplate text for the Foreword. The Foreword of a Magenta book contains the following:

1. Technical Content;2. Boilerplate text stating that the document may evolve and change;3. An up-to-date list of CCSDS Member and Observer Agencies.

4 If you end up including this text as a placeholder, include a disclaimer at the top similar to that provided for the Statement of Authority. Also, know that even though you may have seen them bolded in CCSDS books, do not bold the words "Practice" and "Recommended Practice" here.

Magenta Book Job Aid Page 5 of 13 July 2013

Page 6: Recommended Practice (Magenta Book) Job Aids Toolkit/Job Aids... · Web viewRecommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document-development

Author’s ToolkitTechnical Content

The intended use and audience for the document shall be identified in the foreword. (The technical editor provides the content.)

Document Evolution Boilerplate Text5

For all documents, the following boilerplate text shall follow the technical content of the foreword:

Through the process of normal evolution, it is expected that expansion, deletion, or modification of this document may occur. This document is therefore subject to CCSDS document management and change control procedures which are defined in Organization and Processes for the Consultative Committee for Space Data Systems (CCSDS A02.1-Y-3). Current versions of CCSDS documents are maintained at the CCSDS Web site:

http://www.ccsds.org/

Questions relating to the contents or status of this document should be addressed to the CCSDS Secretariat at the address indicated on page i.

List of Member and Observer Agencies

The mandatory introductory text and agency lists are on the following page. 6

5 1) Per Tom Gannett confirmation July 2013, the term "this document" is fine to be left here; however, it may later be changed to the book type (e.g., "Recommended Practice"). The template has the wording “Recommended Practice” in it.2) The template's inclusion of the yellow book # as shown above is correct; however, the current (2011) version of the Publications Manual does not include the number.6 July 2013 update: The list has been revised to reflect the name change for the South African member agency.

Magenta Book Job Aid Page 6 of 13 July 2013

Page 7: Recommended Practice (Magenta Book) Job Aids Toolkit/Job Aids... · Web viewRecommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document-development

Author’s Toolkit

At time of publication, the active Member and Observer Agencies of the CCSDS were:Member Agencies

Agenzia Spaziale Italiana (ASI)/Italy. Canadian Space Agency (CSA)/Canada. Centre National d’Etudes Spatiales (CNES)/France. China National Space Administration (CNSA)/People’s Republic of China. Deutsches Zentrum für Luft- und Raumfahrt e.V. (DLR)/Germany. European Space Agency (ESA)/Europe. Federal Space Agency (FSA)/Russian Federation. Instituto Nacional de Pesquisas Espaciais (INPE)/Brazil. Japan Aerospace Exploration Agency (JAXA)/Japan. National Aeronautics and Space Administration (NASA)/USA. UK Space Agency/United Kingdom.

Observer Agencies

Austrian Space Agency (ASA)/Austria. Belgian Federal Science Policy Office (BFSPO)/Belgium. Central Research Institute of Machine Building (TsNIIMash)/Russian Federation. China Satellite Launch and Tracking Control General, Beijing Institute of Tracking and

Telecommunications Technology (CLTC/BITTT)/China. Chinese Academy of Sciences (CAS)/China. Chinese Academy of Space Technology (CAST)/China. Commonwealth Scientific and Industrial Research Organization (CSIRO)/Australia. Danish National Space Center (DNSC)/Denmark. Departamento de Ciência e Tecnologia Aeroespacial (DCTA)/Brazil. European Organization for the Exploitation of Meteorological Satellites (EUMETSAT)/Europe. European Telecommunications Satellite Organization (EUTELSAT)/Europe. Geo-Informatics and Space Technology Development Agency (GISTDA)/Thailand. Hellenic National Space Committee (HNSC)/Greece. Indian Space Research Organization (ISRO)/India. Institute of Space Research (IKI)/Russian Federation. KFKI Research Institute for Particle & Nuclear Physics (KFKI)/Hungary. Korea Aerospace Research Institute (KARI)/Korea. Ministry of Communications (MOC)/Israel. National Institute of Information and Communications Technology (NICT)/Japan. National Oceanic and Atmospheric Administration (NOAA)/USA. National Space Agency of the Republic of Kazakhstan (NSARK)/Kazakhstan. National Space Organization (NSPO)/Chinese Taipei. Naval Center for Space Technology (NCST)/USA. Scientific and Technological Research Council of Turkey (TUBITAK)/Turkey. South African National Space Agency (SANSA)/Republic of South Africa. Space and Upper Atmosphere Research Commission (SUPARCO)/Pakistan. Swedish Space Corporation (SSC)/Sweden. United States Geological Survey (USGS)/USA.

Magenta Book Job Aid Page 7 of 13 July 2013

Page 8: Recommended Practice (Magenta Book) Job Aids Toolkit/Job Aids... · Web viewRecommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document-development

Author’s ToolkitPreface

A preface is required for DRAFTS of Magenta Books (i.e., White Books and Red Books).

REMINDER (repeat of footnote on page 2): A preface is not normally included in final publications but may be included to provide issue-specific information.

White Book Preface Boilerplate Text7

The White Book Preface text below is already in the Magenta Book template; it will need to be changed for the Red Book and will be removed from the Magenta Book.

This document is a draft CCSDS Recommended Practice. Its ‘White Book’ status indicates that its contents are not stable, and several iterations resulting in substantial technical changes are likely to occur before it is considered to be sufficiently mature to be released for review by the CCSDS Agencies.

Implementers are cautioned not to fabricate any final equipment in accordance with this document’s technical content.

Red Book Preface Boilerplate Text

The text of the preface for draft CCSDS Recommended Practices shall be:

This document is a draft CCSDS Recommended Practice. Its ‘Red Book’ status indicates that the CCSDS believes the document to be technically mature and has released it for formal review by appropriate technical organizations. As such, its technical contents are not stable, and several iterations of it may occur in response to comments received during the review process.

Implementers are cautioned not to fabricate any final equipment in accordance with this document’s technical content.

Document ControlThe document control section shall contain a history of the published issues of the document. The template includes a Document Control page with the format already set up.

The following entries shall be made for each issue of the book, including the current issue:

a) document number;

b) title and issue;

c) issue date;

d) summary of changes; (if appropriate, changes shall be listed in two categories:

changes not compatible with the previous issue; and

changes compatible with the previous issue.

7 FYI only: Per July 2013 confirmation from Tom Gannet, the bolded “not” is appropriate here.

Magenta Book Job Aid Page 8 of 13 July 2013

Page 9: Recommended Practice (Magenta Book) Job Aids Toolkit/Job Aids... · Web viewRecommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document-development

Author’s Toolkit

Section 1 (Introduction) Particulars(Repeated from earlier): The introduction of the document shall identify and define the document, present conventions used in and definitions specific to the document, and provide a list of referenced documents.

Definitions

The Definitions section may include the subsections of Terms, Nomenclature, and Conventions. The Nomenclature section is mandatory; the other two should be provided if needed.

Terms

Terms specific to the document must be listed. The text used to introduce the list of terms shall be:

For the purposes of this document the following definitions apply.

Generally, the CCSDS definition format follows that of the definition of terse style, as shown below:

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.

Detailed formatting guidance for definitions is provided in 3.4.1.6 of the Publications Manual. Due to its “editorial pitfall” nature, some of that guidance was emphasized in the April 2013

Technical Editor Boot Camp slides. Highlighted in the boot camp were the following items:

3.4.1.6.1 Terms . Terms specific to the document shall be listed . . . .

b) The principal definition of the term shall. . .

– be expressed as a phrase in the same grammatical form as the term (i.e., as the same part of speech);

. . .c) Additional normative qualifying statements, if needed, shall

– be placed, without break, after the principal definition;– be phrased as complete sentences terminated by periods.

d) Informative statements related to a term or its definition, if needed, shall be rendered as notes on the next line following the respective term and definition.

The Boot Camp slides also drew attention to ISO definitions:

“Note: Terms adopted from ISO documents, e.g., ISO/IEC 7498-1, need to be in the same form as in the ISO specification.”

The slides provided a sample definition taken from ISO/IEC 7498-1:

“peer-(N)-entities: Entities within the same (N)-layer.”

The April 2013 Boot Camp presentation stressed the importance of consulting the SANA registry of terms and definitions used in existing CCSDS documents before a term is defined in a new

Magenta Book Job Aid Page 9 of 13 July 2013

Page 10: Recommended Practice (Magenta Book) Job Aids Toolkit/Job Aids... · Web viewRecommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document-development

Author’s Toolkitdocument. Consulting the registry (http:// sanaregistry.org/r/glossary/glossary.html ) will help ensure a term is not being redefined arbitrarily.

Nomenclature Boilerplate Text

A Nomenclature subsection must be included in the Definitions section of normative-track documents (under the Terms subsection, if one is included) 8.

The nomenclature subsection shall identify any specific linguistic usages that apply in the document. For normative-track documents, the following boilerplate text shall be placed in this subsection9:

1.{n} NOMENCLATURE

1.{n}.1 NORMATIVE TEXT

The following conventions apply for the normative specifications in this document:

a) the words ‘shall’ and ‘must’ imply a binding and verifiable specification;

b) the word ‘should’ implies an optional, but desirable, specification;

c) the word ‘may’ implies an optional specification;

d) the words ‘is’, ‘are’, and ‘will’ imply statements of fact.

NOTE – These conventions do not imply constraints on diction in text that is clearly informative in nature.

1.{n}.2 INFORMATIVE TEXT

In the normative sections of this document, informative text is set off from the normative specifications either in notes or under one of the following subsection headings:

– Overview;

– Background;

– Rationale;

– Discussion.

8 The Nomenclature numbering level will vary depending on if there is a Terms subsection or not. 9 The Publications Manual uses the term “this document” as is shown in the boilerplate text; however, when the document reaches publication stage, the words “this document” will be replaced with “Recommended Practice”.

Magenta Book Job Aid Page 10 of 13 July 2013

Page 11: Recommended Practice (Magenta Book) Job Aids Toolkit/Job Aids... · Web viewRecommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document-development

Author’s Toolkit

References Guidance and Boilerplate Text10

A references subsection shall be included to list publications referenced directly in the text of the document.

1) The list shall include publications whose provisions are required for implementing the specifications contained in the document.

2) If normative references exist, the text used to introduce the list shall be as follows:

The following publications contain provisions which, through reference in this text, constitute provisions of this document. At the time of publication, the editions indicated were valid. All publications are subject to revision, and users of this Recommended Standard are encouraged to investigate the possibility of applying the most recent editions of the publications indicated below. The CCSDS Secretariat maintains a register of currently valid CCSDS publications.

3) The list shall not include the following:

materials that are not publicly available;

publications to which only informative reference is made;

publications that provided only source material in the development of the Recommended Standard, Practice, or Experimental Specification.

4) If the document contains no normative references, the text of the References subsection shall be:

This document contains no normative references.

NOTE – An informative annex can be used to list documents whose provisions are not required for implementing the specifications contained in the document.

Per the April 2013 Technical Editor Boot Camp slides: “Normative references [made within the document] must now be explicit references to relevant sections/clauses/etc. in the referenced

document.”

Back Matter ParticularsAnnex Presentation

If an annex is present, it shall have the following information at the beginning of the first annex page:

a) an annex designator in the form ‘ANNEX {L}’, where L is the annex letter;

b) the annex title;

c) for normative-track documents, one of the following two statements:

– ‘(Normative)’,

– ‘(Informative)’;

d) a brief statement of the purpose of the annex.

In most cases, the first paragraph of an annex should state the purpose of that annex.10 Per July 2013 confirmation from Tom Gannet in reference to the boilerplate text, “‘Publications’ should be used uniformly to refer to the references.”

Magenta Book Job Aid Page 11 of 13 July 2013

Page 12: Recommended Practice (Magenta Book) Job Aids Toolkit/Job Aids... · Web viewRecommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document-development

Author’s ToolkitNormative Annexes

(Repeated from earlier): Normative annexes contain technical information which, because of its length, detail, or specificity, is inappropriate for inclusion in the main sections, but which is necessary for implementation of the specifications in the document.

Informative Annexes

Informative annexes provide ancillary information that is not necessary for implementation of specifications.

Security, SANA, and Patent Considerations Annex (Informative)

Per the April 2013 Technical Editor Boot Camp slides, all “Recommended Practices must contain […an] informative annex containing at least Security Considerations.”

[…] Recommended Practices […] shall contain an informative annex that addresses one or more of the following: Security; Space Assigned Numbers Authority (SANA); Patents.

The Security, SANA, and Patent Considerations Annex shall be the first informative annex.The title of the annex shall reflect its content; i.e.; if the annex contains only security considerations, then its title shall be ‘Security Considerations’.

Security 11

A discussion of security considerations shall be included in the annex for Recommended Standards, Recommended Practices, and Experimental Specifications.

The scope of the discussion shall be security considerations related to implementation of the specifications contained in the document and shall observe the following outline:

– Introduction;

– Security Concerns with Respect to the CCSDS Document:

Data Privacy;

Data Integrity;

Authentication of Communicating Entities;

Control of Access to Resources;

Availability of Resources;

Auditing of Resource Usage;

– Potential Threats and Attack Scenarios (how could someone break the technology and why);

– Consequences of Not Applying Security to the Technology (e.g., loss of life, loss of mission).

Definitions of Terms (Informative)

If definitions of terms used throughout the document are provided as an aid to the reader, lists of these terms shall be placed in the first informative annex following the Security, SANA, and Patent Considerations Annex, if present.

NOTE: The SANA registry has a “CCSDS Abbreviations” link you may find helpful when putting together an acronym list. Bear in mind, however, that while it includes a fair number of acronyms used by CCSDS,

11 The Magenta Book template includes a Security Annex placeholder, complete with section headings.

Magenta Book Job Aid Page 12 of 13 July 2013

Page 13: Recommended Practice (Magenta Book) Job Aids Toolkit/Job Aids... · Web viewRecommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document-development

Author’s Toolkitthe list is not complete, as it does not reflect all acronyms/abbreviations or “variations” of a term as it has been used within CCSDS. To assist you, a separate Excel spreadsheet with acronyms pulled from the CCSDS document library and SANA registry is provided in the Author’s Toolkit area of the CWE.

Magenta Book Job Aid Page 13 of 13 July 2013

Page 14: Recommended Practice (Magenta Book) Job Aids Toolkit/Job Aids... · Web viewRecommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document-development

Author’s Toolkit

Magenta Book Abbreviated ChecklistTEMPLATE

Was the most recent and correct template used?

FRONT MATTER

TITLE PAGE

Series Name: Is the correct series name on the front of the document?WB: Proposed Draft Recommendation for Space Data System PracticesRB: Draft Recommendation for Space Data System PracticesMB: Recommendation for Space Data System Practices

Title: Does the title concisely identify the subject of the document?

Document Type: Is it correct?WB: Proposed Draft Recommended PracticeRB: Proposed Recommended PracticeMB: Recommended Practice

Document Number: Is a document number included? (If not, contact the Secretariat for a number.)

Book Color: Is the correct book color stated—i.e., WHITE BOOK or RED BOOK or MAGENTA BOOK?

Issue Date: Is the Issue Date either the current or an anticipated future month?

REMAINING FRONT MATTER

Authority Page: Does the Authority page have the Issue, Date, and Location accurately filled in the text box?

Statement of Intent: Not necessary for White or Red books. If included as a placeholder, did you include a disclaimer similar to the following?: (WHEN THIS RECOMMENDED PRACTICE IS FINALIZED, IT WILL CONTAIN THE FOLLOWING STATEMENT OF INTENT:)

Foreword: Is document-specific text included in the Foreword?

Preface: Is the document-specific (White Book or Red Book) Preface included?

Document Control: Does the Document Control section reflect the current document’s information, and, if applicable, the history of the published issues of the document?

Table of Contents: Is a Table of Contents provided that includes main section and level-two headings, and, if applicable, the following: annex main headings; table of figures; table of tables?

HEADER AND FOOTER

Header: Does the header reflect the correct stage of the document?WB: Proposed Draft CCSDS Recommended Practice for…RB: Proposed CCSDS Recommended Practice for…MB: CCSDS Recommended Practice for…

Header: Is the title (or a clear variation thereof) included in the header (where the placeholder originally indicated [Subject])?

Footer: If you have a document number, has it replaced its placeholder (000.0-W-0) in the footer?

Footer: Does the date in the footer reflect the date on the Title Page?

SECTION 1: INTRODUCTION

Purpose: Is the purpose of the document identified?

Scope: Is the area to which the document applies defined?

Magenta Book Abbreviated Checklist Page 1 of 2 July 2013

Page 15: Recommended Practice (Magenta Book) Job Aids Toolkit/Job Aids... · Web viewRecommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document-development

Author’s Toolkit

Applicability: Are the implementations to which the document applies defined?

Rationale: Recommended. Are the reasons the book, or a new issue, is being published outlined?

Document Structure: Recommended. Is a section provided that outlines the structure of the document and briefly identifies the contents of each section and annex?

Document Structure: If “yes” was answered to the prior question: Does the document actually follow that structure, and are the section headings a close, if not exact match to the list provided in the Document Structure section??

Definitions: If definitions are included, is this section labeled “Definitions”?

Terms: Are all document-specific terms identified?

Terms: Was the SANA registry of terms consulted to ensure no term was redefined arbitrarily?

Terms: Are the terms correctly formatted?

Terms: If ISO terms have been used, are they in the same form as in the ISO specification?

Nomenclature: Is the mandatory Nomenclature subsection included with its mandatory text?

Conventions: If conventions are applicable, has a Conventions section been included?

References: If publications are referenced directly in the text of the document, has a References section been included?

References: Do all normative references made within the document explicitly point to relevant sections/clauses/etc. in the document referenced?

SECTION 2: OVERVIEW

Is an Overview section included?

SECTIONS 3–N: DOCUMENT MAIN TEXT (A.K.A. TECHNICAL SPECIFICATIONS)

Is each section of the document devoted to a particular division of the subject?

Has each specification been explicitly identified by a unique subsection or paragraph number?

Is the text written in terse style?

Are all comments and explanatory material clearly identified as non-normative?

BACK MATTER (ANNEXES)

If annexes are included, is each appropriately labeled to include (Normative) or (Informative)?

INFORMATIVE ANNEXES

Is a “Security Considerations” annex included as the first informative annex? (Security must be addressed in a Magenta Book.)

If definitions and terms (including an acronym list) are applicable, is a “Definitions and Terms” informative annex included?

Magenta Book Abbreviated Checklist Page 2 of 2 July 2013

Page 16: Recommended Practice (Magenta Book) Job Aids Toolkit/Job Aids... · Web viewRecommended Practice (Magenta Book) Job Aid This job aid and checklist consolidates all required document-development

Author’s Toolkit

Magenta Book—Document Development Page 1 of 1 July 2013