OpenPOWER Library

 1.6.1. Understanding document marking variables in the pom.xml file

Once the document type decision has been made (Work Group Note or Work Group Specification), two additional markings must be considered during the documentation process: the document confidentiality and the document status. The next section, Navigating the OpenPOWER Foundation documentation publishing process, details how these values will change during the publishing process. But, before diving into the process, let us see what values in the document pom.xml file play a role in the document development process.

The document Work Product categorization, security classification, and document status are reflected in the following ways:

  1. The document Work Product type is defined in the document pom.xml file with the <workProduct> variable. Valid settings are workgroupNotes, workgroupSpecification, candidateStandard, and openpowerStandard. Select the appropriate setting in the following section:

    <!-- TODO: Define the appropriate work product type.  These values are defined by the
               IPR Policy. Consult with the Work Group Chair or a Technical Steering
               Committee member if you have questions about which value to select.
    
              If no value is provided below, the document will default to "Work Group
              Notes".-->
    <workProduct>workgroupNotes</workProduct>
    <!-- workProduct>workgroupSpecification</workProduct -->
    <!-- workProduct>candidateStandard</workProduct -->
    <!-- workProduct>openpowerStandard</workProduct -->
  2. The document security is set in the document pom.xml file with the <security> variable. Valid settings are public, foundationConfidential, and workgroupConfidential. Select the appropriate setting in the following section:

    <!-- TODO: Set the appropriate security policy for the document.  For documents
               which are not "public" this will affect the document title page and
               create a vertical running ribbon on the internal margin of the
               security status in all CAPS.  Values and definitions are formally
               defined by the IPR policy.  A layman's definition follows:
    
               public =	                this document may be shared outside the
                                        foundation and thus this setting must be
                                        used only when completely sure it allowed
               foundationConfidential = this document may be shared freely with
                                        OpenPOWER Foundation members but may not be
                                        shared publicly
               workgroupConfidential =  this document may only be shared within the
                                        work group and should not be shared with
                                        other Foundation members or the public
    
               The appropriate starting security for a new document is "workgroupConfidential". -->
    <security>workgroupConfidential</security>
    <!-- security>foundationConfidential</security -->
    <!-- security>public</security -->
  3. The document work flow status is set in the document pom.xml file with the <documentStatus> variable. Valid settings are draft, review, and published. Select the appropriate setting in the following section:

    <!-- TODO: Set the appropriate work flow status for the document.  For documents
               which are not "published" this will affect the document title page
               and create a vertical running ribbon on the internal margin of the 
               security status in all CAPS.  Values and definitions are formally
               defined by the IPR policy.  A layman's definition follows:
    
                   published = this document has completed all reviews and has
                               been published
                   draft =     this document is actively being updated and has
                               not yet been reviewed
                   review =    this document is presently being reviewed
    
               The appropriate starting security for a new document is "draft". -->
    <documentStatus>draft</documentStatus>
    <!-- documentStatus>review</documentStatus -->
    <!-- documentStatus>publish</documentStatus -->
  4. The final place to make updates to a new document is in the <abstract> section of the bk_main.xml file for the document. This section needs to be updated with the appropriate work group information and document information. Typical text appears as follows:

    <!-- TODO: Update the following text with the correct document description (first 
               paragraph), Work Group name, and Work Product track (both in second
               paragraph). -->
    <abstract>
        <para>The purpose of this document is to provide a guide for OpenPOWER
        documentation writers.  As such, it provides directions, policies,
        references, and examples of the XML Docbook environment.  It is intended to be
        used both in final product form (PDF and html) as a document and in source form
        as a template for new documents.</para>
        <para>This document is a Non-standard Track, Work Group Note work product
        owned by the System Software Workgroup and handled in compliance with the
        requirements outlined in the <citetitle>OpenPOWER Foundation Work Group (WG)
        Process</citetitle> document.</para>
    </abstract>

    As stated in the comment text of the book file, the first paragraph provides a typical abstract statement about your particular document. The second paragraph provides more structured text which should be updated with the appropriate Work Group name, Work Product type, and Work Product process. The rest of the information in this paragraph should remain as-is.


loading table of contents...