OpenPOWER Library

 1.6.2. Navigating the OpenPOWER Foundation documentation publishing process

As described in the previous section, Section 1.6.1, “Understanding document marking variables in the pom.xml file”, document markings for work product, document confidentiality, and document status are set by the <workProduct>, <security>, and <documentStatus> variables respectively. Selecting the appropriate value for each variable, however, generally depends on the status of the document in the development process.

The following figures and sub-sections provide detailed information about variable settings and process steps. For these figures, the following standards are used:

  • Rectangle boxes in various shades of blue represent the work product states previous introduced in Section 1.6, “Publishing OpenPOWER Documents”.

  • Green diamonds containing question marks, represent decision points with their key questions in bold green and the answers in standard green text.

  • Red octagons represent actions required in the process such as reviews or approvals. Specific descriptions are noted in bold red text beside the octagon.

  • Black text along the right side of the connecting lines, indicates changes to the various variables in the document pom.xml file.

This flowchart expands upon the Non-Standard Track Work Product lifecycle first introduced in Figure 1.2, “Overview of Non-standard Track Work Products”. Document markings and key process decisions and approvals occur as shown.

 

Figure 1.4. Document work flow for Non-Standard Track Work Products


The only Non-Standard Track Work Product <workProduct> setting is workgroupNotes. Documents in this track have this value set and never changed.

During the work flow progression of the document, a common decision point for the Non-Standard Track Work Product centers on <security> settings. Documents may be marked as public just prior to review or prior to approval. Each work group will need to review their charter and determine whether public release of their work products is expected or allowed.

The <documentStatus> variable tracks quite simply through the work flow, beginning as draft, transitioning to review, and finishing as published when finished.

A feature which makes a Non-Standard Track document unique is that the Work Group is the only approver prior to publish as a Work Group Note. As will be seen in the next figure, Standard Track Work Products often require multiple reviews.

The following flowchart expands upon the Standard Track Work Product lifecycle first introduced in Figure 1.3, “Overview of Standard Track Work Products”. Document markings and key process decisions and approvals reflect a more complex process than the previous one for Non-Standard Work Products.

 

Figure 1.5. Document work flow for Standard Track Work Products


Like Non-Standard Track Work Products, Standard Track documents frequently evaluate the appropriate security setting. Unlike them, Standard Track Work Products involve many more steps, require numerous approval cycles, and ultimately create a public document (<security>public</security>) when they become a Candidate OpenPOWER Standard Work Product.

While the <workProduct> type has a value of workgroupSpecification, the <documentStatus> variable progress as expected -- beginning as draft, transitioning to review, and finishing as published.

Unlike the Non-Standard Work Product, the <workProduct> variable begins as workgroupSpecification, but may transition to candidateStandard as it is proposed to be a Candidate OpenPOWER Standard Work Product and ultimately becomes openpowerStandard if the document is approved as an OpenPOWER Standard Work Product. In these latter work flow stages, the <documentStatus> and <security>remain as published and public respectively and never change. However, it is work noting that a document may simply exist as a Work Group Specification Work Product for its whole lifecycle. Progression through Candidate OpenPOWER Standard to OpenPOWER Standard is an optional step.

For a deeper look at the process, see the next section, Understanding the specific steps of Standard Work Product documents, for step-by-step descriptions of the Standard Product work flow.


loading table of contents...