<!--
Copyright (c) 2016 OpenPOWER Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<section version= "5.0" xml:lang= "en" xmlns= "http://docbook.org/ns/docbook" xmlns:xi= "http://www.w3.org/2001/XInclude"
xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_process">
<title xml:id= "section_template_process_title" > Publishing OpenPOWER Documents</title>
<para > The <citetitle > OpenPOWER Foundation Work Group (WG) Process</citetitle> 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.</para>
<para > 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.</para>
<para > 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.</para>
<para > Non-standard Track Work Products exist simply as Work Group Notes. Their document
lifecycle follows this simplified workflow:</para>
<figure pgwide= "1" xml:id= "project_process_non-std_track_label" >
<title > Overview of Non-standard Track Work Products</title>
<mediaobject >
<imageobject >
<imagedata fileref= "figures/project_process_non-std_track_graphic.svg" format= "SVG" scalefit= "1" width= "100%" />
</imageobject>
</mediaobject>
</figure>
<para > 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.</para>
<para > 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).</para>
<?hard-pagebreak?>
<para > 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:</para>
<figure pgwide= "1" xml:id= "project_process_std_track_label" >
<title > Overview of Standard Track Work Products</title>
<mediaobject >
<imageobject >
<imagedata fileref= "figures/project_process_std_track_graphic.svg" format= "SVG" scalefit= "1" width= "100%" />
</imageobject>
</mediaobject>
</figure>
<para > 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.</para>
<para > The following sections will provide additional details about how to control the document markings
and what the process that dictates those markings:</para>
<itemizedlist >
<listitem >
<para > <xref linkend= "section_template_process_pom" endterm= "section_template_process_pom_title" /> </para>
</listitem>
<listitem >
<para > <xref linkend= "section_template_process_flowchart" endterm= "section_template_process_flowchart_title" /> </para>
</listitem>
<listitem >
<para > <xref linkend= "section_template_process_stdWP_steps" endterm= "section_template_process_stdWP_steps_title" /> </para>
</listitem>
</itemizedlist>
<section xml:id= "section_template_process_pom" >
<title xml:id= "section_template_process_pom_title" > Understanding document marking variables in the pom.xml file</title>
<para > 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,
<xref linkend= "section_template_process_flowchart" endterm= "section_template_process_flowchart_title" /> ,
details how these values will change during the publishing process. But, before diving into the process,
let us see what values in the document <literal > pom.xml</literal> file play a role in the document
development process.</para>
<para > The document Work Product categorization, security classification, and document status are reflected
in the following ways:</para>
<orderedlist >
<listitem >
<para > The document Work Product type is defined in the document <literal > pom.xml</literal> file with the
<literal > < workProduct></literal> variable. Valid settings are <literal > workgroupNotes</literal> ,
<literal > workgroupSpecification</literal> , <literal > candidateStandard</literal> , and <literal > openpowerStandard</literal> .
Select the appropriate setting in the following section:
<programlisting > < ![CDATA[<!-- 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 --> ]]></programlisting> </para>
</listitem>
<listitem >
<para > The document security is set in the document <literal > pom.xml</literal> file with the
<literal > < security></literal> variable. Valid settings are <literal > public</literal> ,
<literal > foundationConfidential</literal> , and <literal > workgroupConfidential</literal> .
Select the appropriate setting in the following section:
<programlisting > < ![CDATA[<!-- 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 --> ]]></programlisting> </para>
</listitem>
<listitem >
<para > The document work flow status is set in the document <literal > pom.xml</literal> file with the
<literal > < documentStatus></literal> variable. Valid settings are <literal > draft</literal> ,
<literal > review</literal> , and <literal > published</literal> .
Select the appropriate setting in the following section:
<programlisting > < ![CDATA[<!-- 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 --> ]]></programlisting> </para>
</listitem>
<listitem >
<para > The final place to make updates to a new document is in the <literal > < abstract></literal> section of
the <literal > bk_main.xml</literal> file for the document. This section needs to be updated with the appropriate
work group information and document information. Typical text appears as follows:
<programlisting > < ![CDATA[<!-- 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> ]]></programlisting> </para>
<para > 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.</para>
</listitem>
</orderedlist>
</section>
<section xml:id= "section_template_process_flowchart" >
<title xml:id= "section_template_process_flowchart_title" > Navigating the OpenPOWER Foundation
documentation publishing process</title>
<para > As described in the previous section,
<xref linkend= "section_template_process_pom" /> , document
markings for work product, document confidentiality, and document status are set by the
<literal > < workProduct> </literal> , <literal > < security> </literal> , and
<literal > < documentStatus> </literal> variables respectively. Selecting the appropriate value
for each variable, however, generally depends on the status of the document in the development process.</para>
<para > The following figures and sub-sections provide detailed information about variable settings and process
steps. For these figures, the following standards are used:</para>
<itemizedlist >
<listitem >
<para > Rectangle boxes in various shades of blue represent the work product states previous introduced in
<xref linkend= "section_template_process" /> .</para>
</listitem>
<listitem >
<para > Green diamonds containing question marks,
represent decision points with their key questions in bold green and the answers in standard green text.</para>
</listitem>
<listitem >
<para > Red octagons represent actions required in the process such as reviews or approvals.
Specific descriptions are noted in bold red text beside the octagon.</para>
</listitem>
<listitem >
<para > Black text along the right side of the connecting lines, indicates changes to the
various variables in the document <literal > pom.xml</literal> file.</para>
</listitem>
</itemizedlist>
<?hard-pagebreak?>
<para > This flowchart expands upon the Non-Standard Track Work Product lifecycle
first introduced in <xref linkend= "project_process_non-std_track_label" /> . Document markings and key
process decisions and approvals occur as shown.</para>
<figure pgwide= "1" xml:id= "project_process_non-std_track_doc_variables_label" >
<title > Document work flow for Non-Standard Track Work Products</title>
<mediaobject >
<imageobject >
<imagedata fileref= "figures/project_process_non-std_track_doc_variables_graphic.svg" format= "SVG" scalefit= "1" width= "80%" align= "center" />
</imageobject>
</mediaobject>
</figure>
<para > The only Non-Standard Track Work Product <literal > < workProduct> </literal> setting is <literal > workgroupNotes</literal> .
Documents in this track have this value set and never changed.</para>
<para > During the work flow progression of the document, a common decision point for the Non-Standard Track Work Product
centers on <literal > < security> </literal> settings. Documents may be marked as <literal > public</literal>
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.</para>
<para > The <literal > < documentStatus> </literal> variable tracks quite simply through the work flow, beginning as
<literal > draft</literal> , transitioning to <literal > review</literal> , and finishing as <literal > published</literal> when finished.</para>
<para > 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.</para>
<para > The following flowchart expands upon the Standard Track Work Product lifecycle
first introduced in <xref linkend= "project_process_std_track_label" /> . Document markings and key
process decisions and approvals reflect a more complex process than the previous one for Non-Standard Work Products.</para>
<?hard-pagebreak?>
<figure pgwide= "1" xml:id= "project_process_std_track_doc_variables_label" >
<title > Document work flow for Standard Track Work Products</title>
<mediaobject >
<imageobject >
<imagedata fileref= "figures/project_process_std_track_doc_variables_graphic.svg" format= "SVG" scalefit= "1" width= "58%" align= "center" />
</imageobject>
</mediaobject>
</figure>
<para > 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 (<literal > < security> public< /security> </literal> ) when they become a
Candidate OpenPOWER Standard Work Product.</para>
<para > While the <literal > < workProduct> </literal> type has a value of <literal > workgroupSpecification</literal> ,
the <literal > < documentStatus> </literal> variable progress as expected -- beginning as
<literal > draft</literal> , transitioning to <literal > review</literal> , and finishing as <literal > published</literal> .</para>
<para > Unlike the Non-Standard Work Product, the <literal > < workProduct> </literal> variable begins as
<literal > workgroupSpecification</literal> , but may
transition to <literal > candidateStandard</literal> as it is proposed to be a Candidate OpenPOWER Standard Work Product
and ultimately becomes <literal > openpowerStandard</literal> if the document is approved as an OpenPOWER Standard Work Product.
In these latter work flow stages, the <literal > < documentStatus> </literal> and <literal > < security> </literal> remain as
<literal > published</literal> and <literal > public</literal> 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.</para>
<para > For a deeper look at the process, see the next section,
<xref linkend= "section_template_process_stdWP_steps" endterm= "section_template_process_stdWP_steps_title" /> , for step-by-step
descriptions of the Standard Product work flow.</para>
</section>
<section xml:id= "section_template_process_stdWP_steps" >
<title xml:id= "section_template_process_stdWP_steps_title" > Understanding the specific steps of Standard Work Product documents</title>
<para > <xref linkend= "section_template_process_flowchart" /> provides an overview of the work flow of both Non-Standard and
Standard Work Products. While <xref linkend= "project_process_non-std_track_doc_variables_label" /> is rather straightforward,
<xref linkend= "project_process_std_track_doc_variables_label" /> 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.</para>
<para > 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.</para>
<?hard-pagebreak?>
<para > 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
<literal > < workProduct> workgroupSpecification< /workProduct> </literal> and
<literal > < documentStatus> draft< /documentStatus> </literal> in their document POM (<literal > pom.xml</literal> ).</para>
<figure pgwide= "1" xml:id= "project_process_std_track_doc_variables_draft_graphic_label" >
<title > Document work flow for Standard Track Work Products in the Specification Draft State</title>
<mediaobject >
<imageobject >
<imagedata fileref= "figures/project_process_std_track_doc_variables_draft_graphic.svg" format= "SVG" scalefit= "1" width= "80%" align= "center" />
</imageobject>
</mediaobject>
</figure>
<para > 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 (<literal > pom.xml</literal> ) variable
<literal > < documentStatus> </literal> should be set to <literal > review</literal> . In addition, the
<literal > < security> </literal> variable may be set to <literal > public</literal> if the review is targeted to be public.</para>
<?hard-pagebreak?>
<para > For documents currently in Work Group Specification Review Draft state
(<literal > < workProduct> workgroupSpecification< /workProduct> </literal> and
<literal > < documentStatus> review< /documentStatus> </literal> ),
consult this figure.</para>
<figure pgwide= "1" xml:id= "project_process_std_track_doc_variables_review_draft_graphic_label" >
<title > Document work flow for Standard Track Work Products in the Specification Review Draft State</title>
<mediaobject >
<imageobject >
<imagedata fileref= "figures/project_process_std_track_doc_variables_review_draft_graphic.svg" format= "SVG" scalefit= "1" width= "80%" align= "center" />
</imageobject>
</mediaobject>
</figure>
<para > 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 (<literal > pom.xml</literal> ) variable
<literal > < documentStatus> </literal> should be set to <literal > published</literal> . In addition, the
<literal > < security> </literal> variable should be set to <literal > public</literal> if for public specifications.</para>
<?hard-pagebreak?>
<para > For Work Group Specifications marked
<literal > < workProduct> workgroupSpecification< /workProduct> </literal> and
<literal > < documentStatus> published< /documentStatus> </literal> ,
see the next figure.</para>
<figure pgwide= "1" xml:id= "project_process_std_track_doc_variables_specification_graphic_label" >
<title > Document work flow for Standard Track Work Products in the Specification State</title>
<mediaobject >
<imageobject >
<imagedata fileref= "figures/project_process_std_track_doc_variables_specification_graphic.svg" format= "SVG" scalefit= "1" width= "80%" align= "center" />
</imageobject>
</mediaobject>
</figure>
<para > A document in the Work Group Specification state may return to a Work Group Specification Draft or
proceed as a Candidate OpenPOWER Standard.</para>
<para > To make updates, the document returns to the Work Group Specification Draft state. To
accomplish this, the <literal > < documentStatus> </literal> variable should be set to <literal > draft</literal> and
<literal > < security> </literal> should be set to either <literal > public</literal> or
<literal > workgroupConfidential</literal> .</para>
<para > 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 <literal > < workProduct> </literal> variable should be set to <literal > candidateStandard</literal> and
<literal > < security> </literal> should be set to <literal > public</literal> .</para>
<?hard-pagebreak?>
<para > For documents currently in Work Group Candidate OpenPOWER Standard state
(<literal > < workProduct> candidateStandard< /workProduct> </literal> and
<literal > < documentStatus> published< /documentStatus> </literal> ),
reference the following figure.</para>
<figure pgwide= "1" xml:id= "project_process_std_track_doc_variables_candidate_graphic_label" >
<title > Document work flow for Standard Track Work Products in the Candidate OpenPOWER Standard State</title>
<mediaobject >
<imageobject >
<imagedata fileref= "figures/project_process_std_track_doc_variables_candidate_graphic.svg" format= "SVG" scalefit= "1" width= "80%" align= "center" />
</imageobject>
</mediaobject>
</figure>
<para > 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.</para>
<para > 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 <literal > < documentStatus> </literal> variable should be set to <literal > draft</literal> and
<literal > < security> </literal> should be set to either <literal > public</literal> or
<literal > workgroupConfidential</literal> depending on how the Work Group handles document drafts.</para>
<para > 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 (<literal > pom.xml</literal> ) variable
<literal > < workProduct> </literal> should be set to <literal > openpowerStandard</literal> .</para>
</section>
<section xml:id= "section_template_packaging_document_for_publish" >
<title xml:id= "section_template_packaging_document_for_publish_title" > Packaging the document for publish</title>
<para > The OpenPOWER Foundation process for publishing documents from WordPress in the
Resource Catalog on openpowerfoundatoin.org website has the following requirements:</para>
<itemizedlist >
<listitem >
<para > The PDF and all HTML source must be bundled in a self-contained zip file.</para>
</listitem>
<listitem >
<para > The zip file is expected to contain a single directory in which the document PDF and <literal > index.html</literal> file are found.</para>
</listitem>
<listitem >
<para > The filename of the zip file must be the same name as the contained directory.</para>
</listitem>
</itemizedlist>
<para > To create this package for the <citetitle > Documentation Development Guide</citetitle> , one would perform the following commands
in Linux from the document source directory (<literal > .../Docs-Template/template/</literal> ):
<screen > <prompt > Docs-Template/template$ </prompt> <userinput > cd target/docbkx/webhelp/</userinput>
<prompt > Docs-Template/template/target/docbkx/webhelp$ </prompt> <userinput > ls</userinput>
doc-devel-guide
<prompt > Docs-Template/template/target/docbkx/webhelp$ </prompt> <userinput > zip -rv doc-devel-guide.zip doc-devel-guide/</userinput>
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
<prompt > Docs-Template/template/target/docbkx/webhelp/doc-devel-guide$ </prompt> <userinput > ls</userinput>
doc-devel-guide doc-devel-guide.zip</screen> </para>
<para > For MacOS and Windows, the steps will be similar with slight variations on the command to create the zip file.</para>
<para > This zip file can be sent to the person managing the documents in the OpenPOWER Resource Catalog.</para>
</section>
</section>
