The OpenPOWER Foundation Work Group (WG) Process document found in the OpenPOWER Foundation Members Community documents is the definitive guide for understanding OpenPOWER Foundation documents and their work flow. Details such as the duration and types of reviews as well as approval voting specifics are found in this document. This section of the guide does not attempt to provide process details, but instead strives to provide an overview to help writers understand enough of the basics to know how to prepare their document and what to expect as they proceed through various stages of document development from first draft to publication. The first key concept to understand about OpenPOWER Foundation documents and the first decision to make when creating a new document is available document types or "Work Products". These fall into one of two categories -- Standards Track or Non-standards Track -- with the simple distinguishing factor being use. If the purpose of a document is to define a specification or standard for hardware or software, then the document is "Standards Track". Everything else is "Non-standards Track." For example, this document is a Non-Stardard Work Product as noted on the title page and the lower right corner of every subsequent page. Non-standard Track Work Products exist simply as Work Group Notes. Their document lifecycle follows this simplified workflow:

Non-standard Track, Work Group Notes begin as Drafts and drop the "Draft" annotation once reviewed. As shown in the figure, the document lifecycle always returns to a "Draft" form for updates and new versions as needed. At any step in cycle, these documents may have security classifications as Public (non-confidential), Members-only (OpenPOWER Foundation Confidential), or Work-Group only (OpenPOWER Work Group Confidential) which will in turn dictate the review context (public or private). Standards Track Work Products begin their life as Work Group Specification and may ultimately become an OpenPOWER Standard. Their document lifecycle is defined in the following illustration:

Standard Track Work Products begin their lives as Work Group Specifications and have security classifications of Public (non-confidental), Members-only (OpenPOWER Foundation Confidental), or Work Group-only (OpenPOWER Work Group Confidential). The security classification impacts the review type -- either public or internal to the Foundation -- as appropriate. Only Work Group Specifications classified as Public may proceed into OpenPOWER Standard Documents. Confidential documents will remain Work Group Specifications. The following sections will provide additional details about how to control the document markings and what the process that dictates those markings:

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, , 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: 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: workgroupNotes ]]> 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: workgroupConfidential ]]> 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: draft ]]> 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: 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. 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 OpenPOWER Foundation Work Group (WG) Process document. ]]> 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.

As described in the previous section, , 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 . 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 . Document markings and key process decisions and approvals occur as shown.

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 . Document markings and key process decisions and approvals reflect a more complex process than the previous one for Non-Standard 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, , for step-by-step descriptions of the Standard Product work flow.

provides an overview of the work flow of both Non-Standard and Standard Work Products. While is rather straightforward, is larger and more complex. In an attempt to simplify the process, the following figures decompose each state into just the actions needed to progress to the next step for Standard Track Work Products. For detailed assistance with the development of Standard Track Work Products, select the figure which reflects your current document state. Then, follow the work flow to understand both the document settings and actions needed to progress to the next document state. For documents either getting started as Work Group Specification Draft or having returned to this state for updates, reference the following figure. Documents in this state will have <workProduct>workgroupSpecification</workProduct> and <documentStatus>draft</documentStatus> in their document POM (pom.xml).

To proceed from a Work Group Specification Draft to a Work Group Specification Review Draft, a document requires 3 approvals, in this order: sponsoring Work Group, Technical Steering Committee, and Board of Directors. Following these three approvals, the document POM (pom.xml) variable <documentStatus> should be set to review. In addition, the <security> variable may be set to public if the review is targeted to be public. For documents currently in Work Group Specification Review Draft state (<workProduct>workgroupSpecification</workProduct> and <documentStatus>review</documentStatus>), consult this figure.

To proceed from a Work Group Specification Review Draft to a Work Group Specification, a document requires a successful review and 3 approvals in this order: sponsoring Work Group, Technical Steering Committee, and Board of Directors. Following these three approvals, the document POM (pom.xml) variable <documentStatus> should be set to published. In addition, the <security> variable should be set to public if for public specifications. For Work Group Specifications marked <workProduct>workgroupSpecification</workProduct> and <documentStatus>published</documentStatus>, see the next figure.

A document in the Work Group Specification state may return to a Work Group Specification Draft or proceed as a Candidate OpenPOWER Standard. To make updates, the document returns to the Work Group Specification Draft state. To accomplish this, the <documentStatus> variable should be set to draft and <security> should be set to either public or workgroupConfidential. To proceed to a Candidate OpenPOWER Standard, a document requires 3 approvals, in this order: sponsoring Work Group, Technical Steering Committee, and Board of Directors. Following these three approvals, the <workProduct> variable should be set to candidateStandard and <security> should be set to public. For documents currently in Work Group Candidate OpenPOWER Standard state (<workProduct>candidateStandard</workProduct> and <documentStatus>published</documentStatus>), reference the following figure.

A document in the Work Group Candidate OpenPOWER Standard state may proceed in two directions, back to a Work Group Specification Draft or on to a Candidate OpenPOWER Standard. To make updates to a Work Group Candidate OpenPOWER Standard document, the document returns to the Work Group Specification Draft state. To accomplish this, the <documentStatus> variable should be set to draft and <security> should be set to either public or workgroupConfidential depending on how the Work Group handles document drafts. To proceed to an OpenPOWER Standard, a document requires a successful review and a single approval from the Board of Directors. Following this approval, the document POM (pom.xml) variable <workProduct> should be set to openpowerStandard.

The OpenPOWER Foundation process for publishing documents from WordPress in the Resource Catalog on openpowerfoundatoin.org website has the following requirements: The PDF and all HTML source must be bundled in a self-contained zip file. The zip file is expected to contain a single directory in which the document PDF and index.html file are found. The filename of the zip file must be the same name as the contained directory. To create this package for the Documentation Development Guide, one would perform the following commands in Linux from the document source directory (.../Docs-Template/template/): Docs-Template/template$ cd target/docbkx/webhelp/ Docs-Template/template/target/docbkx/webhelp$ ls doc-devel-guide Docs-Template/template/target/docbkx/webhelp$ zip -rv doc-devel-guide.zip doc-devel-guide/ adding: doc-devel-guide/ (in=0) (out=0) (stored 0%) adding: doc-devel-guide/favicon.ico (in=806) (out=806) (stored 0%) adding: doc-devel-guide/index.html (in=654) (out=385) (deflated 41%) ...snip... adding: doc-devel-guide/doc-devel-guide-20180406.pdf (in=413655) (out=305492) (deflated 26%) ...snip... adding: doc-devel-guide/common/ (in=0) (out=0) (stored 0%) adding: doc-devel-guide/common/main.js (in=5674) (out=2119) (deflated 63%) ...snip... adding: doc-devel-guide/common/jquery/jquery-ui-1.8.2.custom.min.js (in=87032) (out=22729) (deflated 74%) total bytes=3342807, compressed=1332882 -> 60% savings Docs-Template/template/target/docbkx/webhelp/doc-devel-guide$ ls doc-devel-guide doc-devel-guide.zip For MacOS and Windows, the steps will be similar with slight variations on the command to create the zip file. This zip file can be sent to the person managing the documents in the OpenPOWER Resource Catalog.