diff --git a/template/bk_main.xml b/template/bk_main.xml index 16fbe74..86246d5 100644 --- a/template/bk_main.xml +++ b/template/bk_main.xml @@ -22,7 +22,7 @@ document and should not be changed. Use of this value is in in the Abstract section in this file. --> + ]> - 2015, 2016 + 2015, 2016, 2017 OpenPOWER Foundation - Revision 1.0.1 + Revision 1.1.0_pre2 OpenPOWER + If you don't know which one to select, change to "opfExternal" and ask your TSC representative. --> @@ -80,11 +80,42 @@ 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. It was - created using the Master Template Guide version &template_version;. + created using the Document Development Guide version &template_version;. + Comments, questions, etc. can be submitted to the public mailing list for this document at + syssw-doc_devel_guide@mailinglist.openpowerfoundation.org. Additionally, + the #doc-devel channel in the OpenPOWER Foundation Slack room + (openpowerfoundation.slack.com) + can be used to answer more interactive questions. + + 2017-02-17 + + Version 1.1.0 updates: + + + Enhancements document creation to address project creation and update process. + + + Add "git" error to troubleshooting sections until JAR dependency removed. + + + Add optional font installation step to getting started. + + + Provide example usage of OPF Docbook extensions. + + + Extend explanation of versioning policy. + + + Correct, improve miscellenous wording and grammar. + + + + 2016-09-13 diff --git a/template/ch_example.xml b/template/ch_example.xml index 98fbf6d..f6552b2 100644 --- a/template/ch_example.xml +++ b/template/ch_example.xml @@ -215,6 +215,48 @@ main() If code formatting is not quite what you need, simply displaying text "literally" may suffice as follows: This is my literal text. It ignores whitespace. + + + +
+ Examples of OpenPOWER Foundation Docbook extensions + + The OpenPOWER Foundation Maven Plugin supports a number of extensions that are not pure Docbook. These are: + + + Setting text color explicitly + + Text color can be controlled using <phrase role="color"> tags. For example, this + text:A red sentence.]]> produces this sentence: + A red sentence. + Valid colors include either a keyword color name or a numerical RGB specification. Keyword names are common with the HTML 4 specificiation: + aqua, black, blue, fuchsia, gray, + green, lime, maroon, navy, olive, + purple, red, silver, teal, white, + and yellow. Additionally, RGB values can be #nnnnnn where nnnnnn is a hexidecimal color value or + rgb(n1, n2, n3) where n1, n2, and n3 are intergers 0-255. + + + + Inserting line breaks + Line breaks can be introduced using <?linebreak?> tags. For example, this + text:A line break in the middle of text]]> produces this sentence: + A line break in the middle of text + This tag becomes useful in table text spacing. + + + + Inserting page breaks + Page breaks can be introduced using <?hard-pagebreak?> tags. For example, this + text:A page break Between two paragraphs]]> produces this sentence: + A page break Between two paragraphs + This tag becomes useful in placing tables on page. Placing this statement before a large table may prevent it from spanning a page. + Because the XSL template behind the Processing Instruction generates + a ]]> in + the book FO output, this instruction should be used in the outer most blocks of a section to work effectively. Use inside lists and other structural + components may result in the text after the break being dropped. User beware!. + +
diff --git a/template/ch_template_overview.xml b/template/ch_template_overview.xml index b2f487a..9e04783 100644 --- a/template/ch_template_overview.xml +++ b/template/ch_template_overview.xml @@ -21,8 +21,9 @@ xmlns:xlink="http://www.w3.org/1999/xlink"> The OpenPOWER Foundation Documentation Development Guide provides a framework for OpenPOWER public and private - documentation. The goal of the template and this writeup is to promote community contributions - to OpenPOWER documenation and to enable new contributions within a common look and feel. + documentation. The goal of the document is to describe the documentation development + process, to promote community contributions to OpenPOWER documenation and to enable new + contributions with a common look and feel. The major sections of this document addresses the following topics: @@ -31,6 +32,11 @@ xmlns:xlink="http://www.w3.org/1999/xlink"> This section details tools and commands used to contribute to OpenPOWER documentation. All users who are new to OpenPOWER Foundation documentation should start here. + + : + This section provides detailed descriptions of the various project + components and their roles in the documentation creation process. + : This section provides step-by-step instructions on how to create a new document @@ -51,15 +57,10 @@ xmlns:xlink="http://www.w3.org/1999/xlink"> This section explains key document types and the appropriate work flow for publishing OpenPOWER Foundation documents. - - : - This section provides detailed descriptions of the various project - components and their roles in the documentation creation process. - : This section contains the generally accepted guidelines for creating OpenPOWER documentation. Use this section as a reference - for documentation style beyond template provided features. + for documentation source contruction and community process. : @@ -82,11 +83,11 @@ xmlns:xlink="http://www.w3.org/1999/xlink"> provides examples of common documenation constructs in XML. + - diff --git a/template/figures/project_process_non-std_track_doc_variables_graphic.odg b/template/figures/project_process_non-std_track_doc_variables_graphic.odg new file mode 100644 index 0000000..2826841 Binary files /dev/null and b/template/figures/project_process_non-std_track_doc_variables_graphic.odg differ diff --git a/template/figures/project_process_non-std_track_doc_variables_graphic.svg b/template/figures/project_process_non-std_track_doc_variables_graphic.svg new file mode 100644 index 0000000..de04fc3 --- /dev/null +++ b/template/figures/project_process_non-std_track_doc_variables_graphic.svg @@ -0,0 +1,546 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + <workProduct>workgroupNotes</workProduct><documentStatus>draft</documentStatus><security>workgroupConfidential</security> + + + + + + + + + + + + + + + + + + + + + Work Group NoteDraft + + + + + + + + + + + + + + + Work Group Note + + + + + + + + + + + + + + + Work Group NoteReview Draft + + + + + + + <security>public</security> + + + + + + + + + + + + + + + + ? + + + + + + + + + + + + + + + + + + + + + Public review of document? + + + + + + Yes + + + + + + No + + + + + + + + + + + + + <security>public</security> + + + + + + + + + + + + + Yes + + + + + + <documentStatus>review</documentStatus> + + + + + + <documentStatus>published</documentStatus> + + + + + + Document pom.xml variable changes: + + + + + + + + + + + + + <security>workgroupConfidential</security> + + + + + + + + + + + + + + + + ? + + + + + + + Public development of document? + + + + + + Yes + + + + + + No + + + + + + <documentStatus>draft</documentStatus> + + + + + + <security>public</security> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + √ + + + + + + + + + + + + + + Work Group Approval + + + + + + + + + + + + + + + + ? + + + + + + + + + + + + + + <security>workgroupConfidential</security> + + + + + + + + + + + + + + + + ? + + + + + + + Public release of document? + + + + + + No + + + + + + <documentStatus>draft</documentStatus> + + + + + + Material updates needed? + + + + + + Yes + + + + + + No + + + + + + + + + + + + + + + + √ + + + + + + + Review + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/template/figures/project_process_non-std_track_graphic.odg b/template/figures/project_process_non-std_track_graphic.odg index 9e4852d..f144a01 100644 Binary files a/template/figures/project_process_non-std_track_graphic.odg and b/template/figures/project_process_non-std_track_graphic.odg differ diff --git a/template/figures/project_process_non-std_track_graphic.svg b/template/figures/project_process_non-std_track_graphic.svg index 0ebe6cc..b2dd55d 100644 --- a/template/figures/project_process_non-std_track_graphic.svg +++ b/template/figures/project_process_non-std_track_graphic.svg @@ -1,6 +1,6 @@ - - + + @@ -8,7 +8,7 @@ - + @@ -17,26 +17,16 @@ - - - - - - - - - - @@ -83,65 +73,85 @@ - + - - + + + - + - - + + + - + - - + + + - - - - + + + + + + + - - - - - + + + + Work Group NoteDraft + - - - - + + + + + + + - - - - Public, Member Confidential,Work Group Confidential + + + + Work Group Note + - - - Public, Member Confidential,Work Group Confidential + + + + + + + - - - - Work Group NoteDraft + + + + + Work Group NoteReview Draft + - + - Work Group NoteReview Draft + + + - + - Work Group Note + + + diff --git a/template/figures/project_process_std_track_doc_variables_candidate_graphic.odg b/template/figures/project_process_std_track_doc_variables_candidate_graphic.odg new file mode 100644 index 0000000..5d7b33a Binary files /dev/null and b/template/figures/project_process_std_track_doc_variables_candidate_graphic.odg differ diff --git a/template/figures/project_process_std_track_doc_variables_candidate_graphic.svg b/template/figures/project_process_std_track_doc_variables_candidate_graphic.svg new file mode 100644 index 0000000..a22b7fb --- /dev/null +++ b/template/figures/project_process_std_track_doc_variables_candidate_graphic.svg @@ -0,0 +1,420 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Work GroupSpecificationDraft + + + + + + + + + + + + + + + OpenPOWERStandard + + + + + + + + + + + + + + + CandidateOpenPOWERStandard + + + + + + + + + + + + + + + + + + + + + + + + ? + + + + + + + + + + + + + + <security>workgroupConfidential</security> + + + + + + + + + + + + + + + + ? + + + + + + + Public development of document? + + + + + + Yes + + + + + + No + + + + + + <documentStatus>draft</documentStatus> + + + + + + <security>public</security> + + + + + + Material updates needed? + + + + + + Yes + + + + + + + + + + + + + <workProduct>openpowerStandard</workProduct> + + + + + + + + + + + + + + + + + + + + + + + √ + + + + + + + BoD Approval + + + + + + + + + + + + + No + + + + + + <workProduct>candidateStandard</workProduct><documentStatus>published</documentStatus><security>public</security> + + + + + + Document pom.xml variable changes: + + + + + + + + + + + + + From Work Group Specification + + + + + + + + + + + + + To Work Group Specification Review Draft + + + + + + + + + + + + + + + + + + + + + + + √ + + + + + + + Standard Review + + + + + + + + + + + + + + \ No newline at end of file diff --git a/template/figures/project_process_std_track_doc_variables_draft_graphic.odg b/template/figures/project_process_std_track_doc_variables_draft_graphic.odg new file mode 100644 index 0000000..552c5f9 Binary files /dev/null and b/template/figures/project_process_std_track_doc_variables_draft_graphic.odg differ diff --git a/template/figures/project_process_std_track_doc_variables_draft_graphic.svg b/template/figures/project_process_std_track_doc_variables_draft_graphic.svg new file mode 100644 index 0000000..6a034e0 --- /dev/null +++ b/template/figures/project_process_std_track_doc_variables_draft_graphic.svg @@ -0,0 +1,382 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Work GroupSpecificationDraft + + + + + + + + + + + + + + + Work GroupSpecificationReview Draft + + + + + + + + + + + + + + <workProduct>workgroupSpecification</workProduct><documentStatus>draft</documentStatus><security>workgroupConfidential</security> + + + + + + Document pom.xml variable changes: + + + + + + <security>public</security> + + + + + + + + + + + + + + + + ? + + + + + + + Public review of document? + + + + + + Yes + + + + + + No + + + + + + <documentStatus>review</documentStatus> + + + + + + + + + + + + + + + + + + + + + + + √ + + + + + + + Work Group Approval + + + + + + + + + + + + + + + + √ + + + + + + + TSC Approval + + + + + + + + + + + + + + + + √ + + + + + + + BoD Approval + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + To Work Group Specification + + + + + + + + + + + + + From Work Group Specification andCandidate OpenPOWER Standard + + + + + + From New Document + + + + + + + + + + + + + + \ No newline at end of file diff --git a/template/figures/project_process_std_track_doc_variables_graphic.odg b/template/figures/project_process_std_track_doc_variables_graphic.odg new file mode 100644 index 0000000..d0041fa Binary files /dev/null and b/template/figures/project_process_std_track_doc_variables_graphic.odg differ diff --git a/template/figures/project_process_std_track_doc_variables_graphic.svg b/template/figures/project_process_std_track_doc_variables_graphic.svg new file mode 100644 index 0000000..28e3ede --- /dev/null +++ b/template/figures/project_process_std_track_doc_variables_graphic.svg @@ -0,0 +1,1114 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Work GroupSpecification + + + + + + + + + + + + + + + Work GroupSpecificationReview Draft + + + + + + + + + + + + + + + OpenPOWERStandard + + + + + + + + + + + + + + + CandidateOpenPOWERStandard + + + + + + + + + + + + + + <workProduct>workgroupSpecification</workProduct><documentStatus>draft</documentStatus><security>workgroupConfidential</security> + + + + + + Document pom.xml variable changes: + + + + + + <security>public</security> + + + + + + + + + + + + + + + + ? + + + + + + + Public review of document? + + + + + + Yes + + + + + + No + + + + + + <documentStatus>review</documentStatus> + + + + + + + + + + + + + <security>public</security> + + + + + + + + + + + + + + + + ? + + + + + + + + + + + + + + + + + + + + + Public release of document? + + + + + + Yes + + + + + + <documentStatus>published</documentStatus> + + + + + + + + + + + + + + + + + + + + + + + ? + + + + + + + + + + + + + + <security>workgroupConfidential</security> + + + + + + + + + + + + + + + + ? + + + + + + + Public development of document? + + + + + + Yes + + + + + + No + + + + + + <documentStatus>draft</documentStatus> + + + + + + <security>public</security> + + + + + + Material updates needed? + + + + + + Yes + + + + + + + + + + + + + <workProduct>candidateStandard</workProduct><security>public</security> + + + + + + + + + + + + + No + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ? + + + + + + + + + + + + + + <security>workgroupConfidential</security> + + + + + + + + + + + + + + + + ? + + + + + + + Public development of document? + + + + + + Yes + + + + + + No + + + + + + <documentStatus>draft</documentStatus> + + + + + + <security>public</security> + + + + + + Material updates needed? + + + + + + Yes + + + + + + + + + + + + + <workProduct>openpowerStandard</workProduct> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + √ + + + + + + + Work Group Approval + + + + + + + + + + + + + + + + √ + + + + + + + TSC Approval + + + + + + + + + + + + + + + + √ + + + + + + + BoD Approval + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + √ + + + + + + + Work Group Approval + + + + + + + + + + + + + + + + √ + + + + + + + TSC Approval + + + + + + + + + + + + + + + + √ + + + + + + + BoD Approval + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + √ + + + + + + + Work Group Approval + + + + + + + + + + + + + + + + √ + + + + + + + TSC Approval + + + + + + + + + + + + + + + + √ + + + + + + + BoD Approval + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + √ + + + + + + + BoD Approval + + + + + + + + + + + + + No + + + + + + No + + + + + + + + + + + + + + + + + + + + + + + ? + + + + + + + + + + + + + + <security>workgroupConfidential</security> + + + + + + + + + + + + + + + + ? + + + + + + + Public development of document? + + + + + + Yes + + + + + + No + + + + + + <documentStatus>draft</documentStatus> + + + + + + Material updates needed? + + + + + + Yes + + + + + + + + + + + + + + + + + + + + No + + + + + + + + + + + + + + + + + + + + + + + √ + + + + + + + Specification Review + + + + + + + + + + + + + + + + + + + + + + + √ + + + + + + + Standard Review + + + + + + + + + + + + + <security>public</security> + + + + + + + + + + + + + + + + + + + + + Work GroupSpecificationDraft + + + + + + + + \ No newline at end of file diff --git a/template/figures/project_process_std_track_doc_variables_review_draft_graphic.odg b/template/figures/project_process_std_track_doc_variables_review_draft_graphic.odg new file mode 100644 index 0000000..d086d4e Binary files /dev/null and b/template/figures/project_process_std_track_doc_variables_review_draft_graphic.odg differ diff --git a/template/figures/project_process_std_track_doc_variables_review_draft_graphic.svg b/template/figures/project_process_std_track_doc_variables_review_draft_graphic.svg new file mode 100644 index 0000000..9d8f895 --- /dev/null +++ b/template/figures/project_process_std_track_doc_variables_review_draft_graphic.svg @@ -0,0 +1,553 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Work GroupSpecification + + + + + + + + + + + + + + + Work GroupSpecificationReview Draft + + + + + + + <security>public</security> + + + + + + + + + + + + + + + + ? + + + + + + + + + + + + + + + + + + + + + Public release of document? + + + + + + Yes + + + + + + <documentStatus>published</documentStatus> + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + √ + + + + + + + Work Group Approval + + + + + + + + + + + + + + + + √ + + + + + + + TSC Approval + + + + + + + + + + + + + + + + √ + + + + + + + BoD Approval + + + + + + + + + + + + + + + + + + + + + + + + + + + No + + + + + + To Candidate OpenPOWER Standard + + + + + + From Work Group Specification Draft + + + + + + <workProduct>workgroupSpecification</workProduct><documentStatus>review</documentStatus> + + + + + + Document pom.xml variable changes: + + + + + + + + + + + + + + Work GroupSpecificationDraft + + + + + + + + + + + + + + + + + ? + + + + + + + + + + + + + + <security>workgroupConfidential</security> + + + + + + + + + + + + + + + + ? + + + + + + + Public development of document? + + + + + + Yes + + + + + + No + + + + + + <documentStatus>draft</documentStatus> + + + + + + <security>public</security> + + + + + + Material updates needed? + + + + + + Yes + + + + + + + + + + + + + No + + + + + + To Work Group Specification Review Draft + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + √ + + + + + + + Specification Review + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/template/figures/project_process_std_track_doc_variables_specification_graphic.odg b/template/figures/project_process_std_track_doc_variables_specification_graphic.odg new file mode 100644 index 0000000..345a45a Binary files /dev/null and b/template/figures/project_process_std_track_doc_variables_specification_graphic.odg differ diff --git a/template/figures/project_process_std_track_doc_variables_specification_graphic.svg b/template/figures/project_process_std_track_doc_variables_specification_graphic.svg new file mode 100644 index 0000000..51d5000 --- /dev/null +++ b/template/figures/project_process_std_track_doc_variables_specification_graphic.svg @@ -0,0 +1,459 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Work GroupSpecificationDraft + + + + + + + + + + + + + + + Work GroupSpecification + + + + + + + + + + + + + + + CandidateOpenPOWERStandard + + + + + + + <workProduct>workgroupSpecification</workProduct><documentStatus>published</documentStatus> + + + + + + Document pom.xml variable changes: + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + ? + + + + + + + + + + + + + + <security>workgroupConfidential</security> + + + + + + + + + + + + + + + + ? + + + + + + + Public development of document? + + + + + + Yes + + + + + + No + + + + + + <documentStatus>draft</documentStatus> + + + + + + <security>public</security> + + + + + + Material updates needed? + + + + + + Yes + + + + + + + + + + + + + <workProduct>candidateStandard</workProduct><security>public</security> + + + + + + + + + + + + + No + + + + + + + + + + + + + + + + + + + + + + + √ + + + + + + + Work Group Approval + + + + + + + + + + + + + + + + √ + + + + + + + TSC Approval + + + + + + + + + + + + + + + + √ + + + + + + + BoD Approval + + + + + + + + + + + + + + + + + + + + + + + + + + + To Work Group Specification Review Draft + + + + + + From Work Group Specification Review Draft + + + + + + + + + + + + + To OpenPOWER Standard + + + + + + + + + + + + + + \ No newline at end of file diff --git a/template/figures/project_process_std_track_graphic.odg b/template/figures/project_process_std_track_graphic.odg index 21c8e57..0960c54 100644 Binary files a/template/figures/project_process_std_track_graphic.odg and b/template/figures/project_process_std_track_graphic.odg differ diff --git a/template/figures/project_process_std_track_graphic.svg b/template/figures/project_process_std_track_graphic.svg index 3da0756..afbd985 100644 --- a/template/figures/project_process_std_track_graphic.svg +++ b/template/figures/project_process_std_track_graphic.svg @@ -1,6 +1,6 @@ - - + + @@ -8,7 +8,7 @@ - + @@ -18,32 +18,27 @@ - - - - - - + @@ -85,120 +80,135 @@ - - - - - - - - - - - - - - - - - - - - - - - - - - - + + + + - - - + + + + - - - - - - - - Public, Member Confidential,Work Group Confidential - - - - - Public, Member Confidential,Work Group Confidential + + + + + + + + + + + + + + + + + + Work GroupSpecificationDraft + + + + + + + + + + + + + + + Work GroupSpecification + + + + + + + + + + + + + + + Work GroupSpecificationReview Draft + - - + + + - + - Public + + + - - - - + + + + + + + - - - - - + + + + OpenPOWERStandard + - - - Public + + + + + + + - - - - - + + + + CandidateOpenPOWERStandard + - + - Public, Member Confidential,Work Group Confidential + + + - + - Work GroupSpecificationDraft + + + - + - Work GroupSpecification ReviewDraft - - - - - Work GroupSpecification - - - - - CandidateOpenPOWERStandard - - - - - OpenPOWERStandard + + + diff --git a/template/pom.xml b/template/pom.xml index f685037..12e8739 100644 --- a/template/pom.xml +++ b/template/pom.xml @@ -80,14 +80,14 @@ 1 - 1 + 3 1 - template-guide + doc-devel-guide - template-guide + doc-devel-guide +
+ + Sample section include + This section was developed in a separate file but included in the document by using the following + text: <xi:include href="sec_example.xml"/> + where sec_example.xml is the source file name. + +
diff --git a/template/sec_template_debugging.xml b/template/sec_template_debugging.xml index 82f6f3a..7cf44e6 100644 --- a/template/sec_template_debugging.xml +++ b/template/sec_template_debugging.xml @@ -91,6 +91,10 @@ lineNumber: 272; columnNumber: 70; text not allowed here; expected element "add The location within the file of the syntax error. For the above example, the key information is "lineNumber: 272; columnNumber: 70. + In some XML validation failure scenarios, the lineNumber or + colNumber values are not specified or are -1. If you encounter such a situation, + please post to the Documentation Development mailing list at syssw-doc_devel_guide@mailinglist.openpowerfoundation.org + so they can assist in identifying the exact location of the failure. An explanation of the failure. This information in the above error reads, "text not allowed here; expected element "address", ...". @@ -102,7 +106,7 @@ lineNumber: 272; columnNumber: 70; text not allowed here; expected element "add
Build failures - Build errors are easily identified as well. Below is an example: + Build errors are easily identified as well. Below is the most common example: ... [INFO] ------------------------------------------------------------------------ [INFO] BUILD FAILURE @@ -131,6 +135,14 @@ lineNumber: 272; columnNumber: 70; text not allowed here; expected element "add With these details in hand for either error, one simply locates the offending syntax and makes the appropriate correction. Online resources such as those listed in may be helpful. + + When creating new documentation projects, you may encounter the following error during + your first build:... +[ERROR] Failed to execute goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.5:generate-webhelp (generate-webhelp) on project openpower-vector-programming-guide: Execution generate-webhelp of goal org.openpowerfoundation.docs:openpowerdocs-maven-plugin:1.0.5:generate-webhelp failed: One of setGitDir or setWorkTree must be called. -> [Help 1] +... + + This error results from interactions of the maven build process and git. It may be + circumvented by issuing the git init command in your directory.
@@ -154,25 +166,26 @@ Error ... The "org.apache.fop.fo.ValidationException" text indicates that this error was during FO validation. The key pieces of information are as follows: - - - The error type is indicated in the text following the exception indictor. In our case, the error statement is: - "{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:list-block"!. This error clearly - has something to do with the nesting of a "fo:block" statement in a "fo:list-block" statement. - - - The location of the validation error is given in the statement - "See position 70:-1". These two values are the line number and character number of the error. So, our sample - error occurs on line 70, but the character number - of -1 is an indication that the line is too long to effectively point. - - + + + + The error type is indicated in the text following the exception indictor. In our case, the error statement is: + "{http://www.w3.org/1999/XSL/Format}block" is not a valid child of "fo:list-block"!. This error clearly + has something to do with the nesting of a "fo:block" statement in a "fo:list-block" statement. + + + The location of the validation error is given in the statement + "See position 70:-1". These two values are the line number and character number of the error. So, our sample + error occurs on line 70, but the character number + of -1 is an indication that the line is too long to effectively point. + + What this information fails to detail is which file has the problem. To find the particular offending file, one must understand the Docbook build process. This process begins by collecting all XML into a working copy of the main book file. The build failure error in includes a reference to this file which will be found in the .../target/ directory. It generally has the same name as the main book file of the document, which if copied - from the Master Template Guide project, will be bk_main.xml. When in doubt about + from the Documentation Development Guide project, will be bk_main.xml. When in doubt about this file name, you will find it in the <includes> tag in the pom.xml file. Once all information has been pulled into the working XML file, the XML statements are transformed into FO statements @@ -219,7 +232,10 @@ javax.xml.transform.TransformerException: org.apache.fop.fo.ValidationException: DocBook (XML) file. With this information, one can inspect the document source to decide if the error is bad DocBook syntax or a tooling bug. If the latter, please save the newly formatted .fo file and include it in the bug writeup. - Fully understanding the error, may require knowing more about XSL FO syntax. Many such web sites exist for this, but + This error generally indicates a problem with documentation tooling. If you encounter such a situation, + please post to the Documentation Development mailing list at syssw-doc_devel_guide@mailinglist.openpowerfoundation.org + so they can assist in identifying the exact cause of the failure. + If you wish to fully understanding the error, you may require knowing more about XSL FO syntax. Many such web sites exist for this, but the XSL Formatting Objects Summary from W3C (World Wide Web Consortium) provides a good starting reference online at https://www.w3.org/2002/08/XSLFOsummary.html. diff --git a/template/sec_template_existing_document.xml b/template/sec_template_existing_document.xml index b21896d..a92c465 100644 --- a/template/sec_template_existing_document.xml +++ b/template/sec_template_existing_document.xml @@ -23,7 +23,7 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_existing_doc the specific document project. Begin by cloning the master document as described in . Once complete, obtain a copy of the desired document by cloning its project. For example, to clone this document, - Master Template Guide, from the + Documentation Development Guide, from the public OpenPOWER Foundation git repository, use this command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git Cloning into 'Docs-Template'... @@ -36,7 +36,7 @@ Unpacking objects: 100% (62/62), done. Checking connectivity... done. $ - To build a specific document such as the template guide, follow these steps from the directory where + To build a specific document such as this guide, follow these steps from the directory where you just cloned:$ cd Docs-Template/template $ mvn clean [INFO] Scanning for projects... @@ -84,7 +84,7 @@ Checking connectivity... done. Projects may contain multiple documents. While specific documents can be built by executing a mvn clean generate-sources in the specific document directory, executing this command in the base project directory will build all projects identified in the <module> list in the - top-level pom.xml file, known as the "workgroup-pom". + top-level pom.xml file, known as the "Workgroup POM". You are now ready to begin making updates. Before diving deeply into new text, you may want to review diff --git a/template/sec_template_getting_started.xml b/template/sec_template_getting_started.xml index 7d38fe0..8319ac4 100644 --- a/template/sec_template_getting_started.xml +++ b/template/sec_template_getting_started.xml @@ -21,13 +21,16 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_getting_star To begin contributing to the OpenPOWER Foundation documentation, the following steps must be completed: - Installing tools + - Creating accounts + - Cloning master document information + + + + @@ -35,8 +38,8 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_getting_star Once complete, you can proceed to either or as needed. -
- Installing tools +
+ Installing tools Only two tools are required to update documentation, git and maven. Git manages the documentation source and maven provides the build framework to create the published content in PDF and html form. Installation steps for these tools varies by operating system. @@ -69,8 +72,26 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_getting_star can be found at http://bluefish.openoffice.nl/index.html.
+
+ Installing fonts + The OpenPOWER Foundation documentation utilizes opensource fonts known as the + Chrome OS core fonts or Croscore fonts. + The three TrueType fonts (TTFs) in this family Arimo (sans-serif), Tinos (serif), and Cousine (monospace). While + not strictly required to have these fonts on your system, it can be helpful when designing graphics and + other images to have them installed on your development system. + Only two tools are required to update documentation, git and maven. Git manages the documentation + source and maven provides the build framework to create the published content in PDF and html form. + Installation steps for these tools varies by operating system. + On Debian-based Linux operating systems (Ubuntu and Debian), install Croscore fonts as follows: + # apt-get install fonts-croscore + On RPM-based Linux operating systems (Fedora, RHEL, openSUSE, SLES), install Croscore fonts as follows: + # yum install google-croscore-fonts + On Mac OS X and Windows systems, use a font website to download and install the Croscore fonts individually. Most of + these sites provide directions for Mac OS and Windows. +
+
- Creating accounts + Creating accounts All OpenPOWER project documentation is maintained in GitHub trees, public and private. The first step to creating documentation will be joining the GitHub community. To join the GitHub community, @@ -86,10 +107,11 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_getting_star
- Cloning master document information + Cloning master document information To successfully build OpenPOWER Foundation documents, common document files must be in place in addition to the specific document files. These common files are obtained by cloning the OpenPOWER Foundation public project Docs-Master. - To clone the master template document framework use the clone git command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Master.git + To clone the OpenPOWER Foundation master document framework, + use the clone git command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Master.git Cloning into 'Docs-Master'... remote: Counting objects: 24, done. remote: Compressing objects: 100% (18/18), done. diff --git a/template/sec_template_new_document.xml b/template/sec_template_new_document.xml index b76a836..f1b60fe 100644 --- a/template/sec_template_new_document.xml +++ b/template/sec_template_new_document.xml @@ -21,166 +21,260 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_new_document Creating a new document from scratch follows four simple steps: - Cloning the project source. + - Finding a document framework. + - Modifying core project files. + - Adding new document content. + + + Before undertaking one of these activities, it may be helpful to read the + + section to learn the basics about the documentation project structure. -
- Clone the project source. - All documentation projects reside in a project directory maintained in GitHub, just like the - Docs-Master framework described in . In the same directory - where the Docs-Master project has been cloned, you will need to - clone the documentation source for your project. A list of the OpenPOWER Foundation projects can be found at - https://github.com/OpenPOWERFoundation/. Select - the project from this list. - - If you do not see the project for which you are looking, you may not be authorized to it. See - for details about joining the OpenPOWER Foundation private projects. If you - feel that you need a new GitHub project, work with the - Technical Steering Committee Chair, tsc-chair@openpowerfoundation.org, to request and get this setup. +
+ Cloning a project + All documentation projects reside in a Git project directory, either locally or in the cloud at GitHub. + As described in , your document project directory must reside locally in the + same directory as the Docs-Master framework. - To clone an OpenPOWER Foundation project like Docs-Template issue the following - command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git + To clone a project in which to work, select from one of the two approaches below: + + + + + + + + Complete the project cloning and then continue with the next step in + . + +
+ Cloning an existing project + + To work in an existing OpenPOWER Foundation project like the Documentation Development + Guide (Docs-Template), + use the following command in the same directory that contains + Docs-Master:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git Cloning into 'Docs-Template'... -Username for 'https://github.com': my_userid -Password for 'https://my_userid@github.com': my_password -remote: Counting objects: 62, done. -remote: Compressing objects: 100% (10/10), done. -remote: Total 62 (delta 2), reused 0 (delta 0), pack-reused 52 -Unpacking objects: 100% (62/62), done. +remote: Counting objects: 163, done. +remote: Total 163 (delta 0), reused 0 (delta 0), pack-reused 163 +Receiving objects: 100% (163/163), 275.60 KiB | 494.00 KiB/s, done. +Resolving deltas: 100% (96/96), done. Checking connectivity... done. $ The results should look roughly something like above with actual numbers of objects, files, etc. varying - for different projects. + for different projects. + + Private projects prompt for a GitHub userid and and password immediately following the "Cloning into..." message. + When cloning public projects such as Docs-Template, these prompts are skipped. + + A list of additional OpenPOWER Foundation projects can be found at + https://github.com/OpenPOWERFoundation/. To work + on an existing project, note its name it the list and apply the above steps replacing Docs-Template + with your preferred project from the list. + + If you do not see the project for which you are looking, you may not be authorized to it. See + for details about joining the OpenPOWER Foundation private projects. If you + feel that you need a new GitHub project, work with the + Technical Steering Committee Chair, tsc-chair@openpowerfoundation.org, to request and get this setup. + + The existing project should now be cloned. Continue with the next step in + . +
+ +
+ Creating a new project locally + + To create a new project locally, the simplest way is to clone the Documentation Development + Guide (Docs-Template) into a new project. In + our directions, my_project will be our new project name. + Use the following command in the same directory that contains + Docs-Master:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git my_project +Cloning into 'my_project'... +remote: Counting objects: 163, done. +remote: Total 163 (delta 0), reused 0 (delta 0), pack-reused 163 +Receiving objects: 100% (163/163), 275.60 KiB | 494.00 KiB/s, done. +Resolving deltas: 100% (96/96), done. +Checking connectivity... done. +$ The results should look roughly something like above with actual numbers of objects, files, etc. varying + for different projects. + + The new project should now be generally setup. Continue with the next step in + . +
- Private projects prompt for a GitHub userid and and password. When cloning public projects, these prompts - are skipped. - - The base project has now been cloned.
-
- Finding a document framework - If this is your first document, in a brand new project (git tree), you have the fewest number of steps - to perform because your project should have been primed with a single project based on Docs-Template. - You can verify this by inspecting - the files in your project directory. A new project will contain a template directory, a pom.xml - file, a LICENSE file, and a README.md file. If this is the case, you simply - need to perform the following three steps: +
+ Finding a document framework + + When creating a new document, the simplest way to start is to use an existing document. This ensures + that you have a basic document structure and allows you to start with a working document from which to make + changes. Select from one of the following scenarios for detailed directions on creating your document framework: - - - Navigate down to your project directory, called my_project for this example. This can be achieved - using the cd command: -$ cd ~/my_project -$ - This directory should contain the template folder used to prime the project. + + + If your project exits on GitHub in the OpenPOWER Foundation area and it contains a template directory, + then follow the directions in + + to use this document as a base. - Rename the template document directory to something new like my_doc. - To accomplish this, use the mv command:: -$ mv template/ my_doc + If you have an existing document in your project that you want to use as a + base for your new document, then follow the directions in + + to establish your base document. - Change the project name in the workgroup POM.xml file. Using your editor, change this line - between the <modules> and the </modules> tags near the top of the - file:template + Otherwise, the instructions in + + will clone and copy this document as a base. + + + +
+ Moving the template document into your new document framework + + If this is your first document, in a brand new OpenPOWER Foundation project (on GitHub), you have the fewest number of steps + to perform because your project should have been primed with a single project based on Docs-Template. + You can verify this by inspecting + the files in your project directory. A new project will contain a template directory, a pom.xml + file, a LICENSE file, and a README.md file. If this is the case, you simply + need to perform the following three steps: + + + + Navigate down to your project directory, called my_project for this example. This can be achieved + using the cd command: +$ cd ~/my_project +$ + This directory should contain the template folder used to prime the project. + + + Rename the template document directory to something new like my_doc. + To accomplish this, use the mv command:: +$ mv template/ my_doc + + + Change the project name in the Workgroup POM file (my_project/pom.xml). Using your editor, change this line + between the <modules> and the </modules> tags near the top of the + file:template ]]> to read like this:my_doc ]]> - - + + + + Your new document frameword has been copied from the Document Development Guide. + Continue with the next step in + . + +
- If this is not the first document in the project, then you can either begin by copying an existing document or by cloning the - Docs-Template project. To copy an existing project, follow these steps: - - - - Navigate down to your project directory, called my_project for this example. - This can be achieved using the cd command: +
+ Copying an existing document as a new document framework + + If you have another document within your project that would serve as a good base for your new one, + you can copy the existing document as the source for your new document. Follow these steps: + + + + Navigate down to your project directory, called my_project for this example. + This can be achieved using the cd command: $ cd ~/my_project $ - This directory should contain the folder name of the document wishing to be copied, called source_doc - for clarity in these directions. - - - To create a new document directory, simply create a new directory and copy the contents of the source_doc - directory. If creating a new directory named my_doc via a command line, the command - sequence would look like this: + This directory should contain the folder name of the document wishing to be copied, called source_doc + for clarity in these directions. + + + To create a new document directory, simply create a new directory and copy the contents of the source_doc + directory. If creating a new directory named my_doc via a command line, the command + sequence would look like this: $ mkdir my_doc -$ cp -r source_doc/* my_doc +$ cp -r source_doc/*.* my_doc $ - - - Add the new project to the workgroup POM.xml file. Using your editor, add the following lines - between the <modules> and the </modules> tags near the top of the file:my_doc + + + Add the new project to the Workgroup POM file (my_project/pom.xml). + Using your editor, add the following lines + between the <modules> and the </modules> tags near the top of the file:my_doc ]]> - - + + - Instead of copying an existing document, you may want to start with the template document source. The steps to do this - are similar to those above, but with a few more commands. The following commands will create a new document based on the - the master template: + Before committing the project back to git, you will need to add the new directory to the git repository. This can + be performed using the git add my_doc/ command on the whole directory. + + You are now ready to begin making updates to your new document. Continue with the next step in + . + +
+ +
+ Copying the Document Development Guide as a new document framework - - - Navigate down to your project directory, called my_project for this example. - This can be achieved using the cd command: + Instead of copying an existing document, you may want to start with the Document Development Guide + (Doces-Template) source. The steps to do this are similar to those above, but with a few more commands. + The following commands will create a new document based on this guide: + + + + Navigate down to your project directory, called my_project for this example. + This can be achieved using the cd command: $ cd ~/my_project $ - This directory should contain any existing document folders along with at least a pom.xml file, a - LICENSE file, and a README.md file. - - - Clone the the template project into your working directory with this - command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git + This directory should contain any existing document folders along with at least a pom.xml file, a + LICENSE file, and a README.md file. + + + Clone the the Documentation Development Guide + (Docs-Template) project into your working directory with this + command:$ git clone https://github.com/OpenPOWERFoundation/Docs-Template.git Cloning into 'Docs-Template'... -Username for 'https://github.com': my_userid -Password for 'https://my_userid@github.com': my_password -remote: Counting objects: 62, done. -remote: Compressing objects: 100% (10/10), done. -remote: Total 62 (delta 2), reused 0 (delta 0), pack-reused 52 -Unpacking objects: 100% (62/62), done. +remote: Counting objects: 163, done. +remote: Total 163 (delta 0), reused 0 (delta 0), pack-reused 163 +Receiving objects: 100% (163/163), 275.60 KiB | 0 bytes/s, done. +Resolving deltas: 100% (96/96), done. Checking connectivity... done. $ - - - To create a new project directory, simply create a new directory and copy the contents of the Docs-Template/template - directory. If creating a new project named my_doc via a command line, the command - sequence would look like this: + + + To create a new project directory, simply create a new directory and copy the contents of the Docs-Template/template + directory. If creating a new project named my_doc via a command line, the command + sequence would look like this: $ mkdir my_doc $ cp -r Docs-Template/template/* my_doc $ - - - Once copied, the Docs-Template directory and all its contents should be removed from your project so that it does not - accidentally get included in your project. The command rm -rf Docs-Template - - - Finally, add the new project to the workgroup POM.xml file. Using your editor, add the following lines - between the <modules> and the </modules> tags near the top of the file:my_doc -]]> - - + + + Once copied, the Docs-Template directory and all its contents should be removed from your project so that it does not + accidentally get included in your project. The command rm -rf Docs-Template + + + Finally, add the new project to the Workgroup POM file (my_project/pom.xml). + Using your editor, add the following lines + between the <modules> and the </modules> tags near the top of the file:my_doc + ]]> + + + + Before committing the project back to git, you will need to add the new directory to the git repository. This can + be performed using the git add my_doc/ command on the whole directory. - Before committing the project back to git, you will need to add the new directory to the git repository. This can - be performed using the git add my_doc/ command on the whole directory. + You are now ready to begin making updates to your new document. Continue with the next step in + . - - - You are now ready to begin making updates to your new document. The next section will provided detailed steps of where to - get started. +
+
- Modifying core project files + Modifying core project files The first step to customizing a new project is to modify two core project files--pom.xml and bk_main.xml. Within these two files are XML comment tags that begin "<!-- TODO:" to identify places which need customization. The surrounding comments will provide guidance on what needs to change and how @@ -195,7 +289,7 @@ Checking connectivity... done. Be sure to remember two key values you used in the pom.xml file, <webhelpDirname> and <pdfFilenameBase>, as these will be used to locate your generated document. When ready, build your new document using standard maven commands like - this:$ cd my_proj/my_doc + this:$ cd my_project/my_doc $ mvn clean [INFO] Scanning for projects... [INFO] @@ -237,10 +331,14 @@ Checking connectivity... done. The permutations of Maven invocations may be combined into one operation where the parameters are specified in the order in which one wishes to execute them. Thus, the command mvn clean generate-sources would accomplish the same thing as the above sequence of commands. + + You have completed updates to core project files for your new document. Continue with the next step in + . +
-
- Adding new content +
+ Adding new content The starting point for book content is the bk_main.xml file (or whatever to which it was renamed in the previous step). Removal and additions of the main chapter files will be controlled by entries near the @@ -267,7 +365,6 @@ Checking connectivity... done. When creating new files for the project, remember to use the git add <file name> command to add new files to the git tree. -
diff --git a/template/sec_template_policies.xml b/template/sec_template_policies.xml index ff8f382..abd87fc 100644 --- a/template/sec_template_policies.xml +++ b/template/sec_template_policies.xml @@ -18,7 +18,7 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_policies"> Policies and conventions - Most document style policies are established simply by using the template documentation framework. However, + Most document style policies are established simply by using the provided documentation framework. However, by applying some conventions to the document source structure, community members will be able to work across more d ocumentation projects. The recommended documentation structure guidelines are as follows: @@ -27,8 +27,26 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_policies"> The head book file should be named with the prefix "bk_". - The document versioning as defined by the releaseinfo tag in the main book - file bk_xxx should be named "Revision N.N", not "Version N.N" or simply "N.N" + The document versioning as defined by the <releaseinfo> tag in the main book + file bk_xxx should be named "Revision V.R.M", not "Version V.R.M" or simply "V.R.M" where: + + + Significant updates increment the V (Version) value while reseting the R and + M values to 0, + + + Material, but small, updates increment the R (Release) value and reset the M + to 0, and + + + Trivial updates (such as typos and grammatical changes) only need to increment the M (Modifier) + value. + + + Numbering of "pre-release" versions or draft versions of a document may be handled in multiple ways such as + incrementing the previous modifier level until publication and then updating appropriately, setting the releases to + the anticipated level and then appending a "_preN" suffix where "N" can be incremented during drafting. Each Work Group + may set their own policy here. Chapters files should be named with the prefix "ch_". diff --git a/template/sec_template_process.xml b/template/sec_template_process.xml index 88f8391..1c0c652 100644 --- a/template/sec_template_process.xml +++ b/template/sec_template_process.xml @@ -20,23 +20,48 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_process"> Publishing OpenPOWER Documents 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. The section strives to + 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 specification publish. + 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. + 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: + +
+ Overview of Non-standard Track Work Products + + + + + +
+ + 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:
- Document work flow for Standard Track Work Products + Overview of Standard Track Work Products @@ -51,32 +76,42 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_process"> Only Work Group Specifications classified as Public may proceed into OpenPOWER Standard Documents. Confidential documents will remain Work Group Specifications. - Non-standard Track Work Products exist simply as Work Group Notes. Their document - lifecycle follows this simplified workflow: - -
- Document work flow for Non-standard Track Work Products - - - - - -
- - Non-standard Track, Work Group Notes begin as Drafts and drop the "Draft" annotation once reviewed. Like - Standard Track Work Products, they 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). + The following sections will provide additional details about how to control the document markings + and what the process that dictates those markings: - Once these decisions have been made, then they can be reflected into the document 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: + 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, + , + 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: ]]> - + - - 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: + + 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: + + 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 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 the Master Template Guide document is to provide a guide - for OpenPOWER documentation writers. As such, it provides directions, policies, + 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. @@ -157,13 +192,234 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_process"> 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 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. + +
+ +
+ + Navigating the OpenPOWER Foundation + documentation publishing process + + 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. + +
+ 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 . Document markings and key + process decisions and approvals reflect a more complex process than the previous one for Non-Standard Work Products. + + + +
+ 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, + , for step-by-step + descriptions of the Standard Product work flow. + +
+ +
+ + Understanding the specific steps of Standard Work Product documents + + 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). + +
+ Document work flow for Standard Track Work Products in the Specification Draft State + + + + + +
+ + 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. + +
+ Document work flow for Standard Track Work Products in the Specification Review Draft State + + + + + +
+ + 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. + +
+ Document work flow for Standard Track Work Products in the Specification State + + + + + +
+ + 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. + +
+ Document work flow for Standard Track Work Products in the Candidate OpenPOWER Standard State + + + + + +
+ + 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. +
+
diff --git a/template/sec_template_structure.xml b/template/sec_template_structure.xml index 67c8570..5da0ae3 100644 --- a/template/sec_template_structure.xml +++ b/template/sec_template_structure.xml @@ -19,7 +19,7 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_structure"> Understanding the project structure The OpenPOWER Foundation documentation build process involves dependency on a common - framework and shared files. As such a deeper explanation about the relationships of key projects and their + framework and shared files. As such, a deeper explanation about the relationships of key projects and their components may be helpful to prevent and diagnose documentation build problems. This section provides a pictorial layout of key files and explains their roles and relationships. @@ -31,8 +31,8 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_structure"> Docs-Master project. To begin to understand why, let us use a picture. The following graphic illustrates - the directory structure of three projects -- two - Docs-Master and Docs-Template, both existing OpenPOWER Foundation GitHub projects and a + the directory structure of three projects: two existing OpenPOWER Foundation GitHub projects, + Docs-Master and Docs-Template, and a hypothetical new project named my_project.
@@ -58,8 +58,9 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_structure"> Inside the Docs-Masterproject directory, the two most important pieces are a commmon directory and a pom.xml file. The directory contains common files used by all projects such as the common preface - (ch_preface.xml) and the common appendix (app_foundation.xml. The pom.xml file - in this directory serves as the "Master POM" for all builds. This file references the OpenPOWER Maven Plugin JAR + (ch_preface.xml) and the common appendix (app_foundation.xml). The pom.xml file + in this directory serves as the "Master POM" (POM stands for Program Object Model and serves as the main configuration file) + for all builds. This file references the OpenPOWER Maven Plugin JAR (found in the OpenPOWER Foundation Repository at http://openpowerfoundation.org/repo.openpowerfoundation.org/) used to control the OpenPOWER @@ -78,7 +79,7 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_structure"> contains all the Docbook source, directly or through include statements (<xi:include href="..."), to build the document. - For completeness of understanding, a hypothetical project my_project is also depected in red. Like all + For completeness of understanding, a hypothetical project my_project is also depicted in red. Like all OpenPOWER Foundation projects, it is cloned at the correct level, equal to Docs-Master. Like the Docs-Template project, it has a "Workgroup POM" which will differ only in the <modules> section where it will describe two document projects, my_doc_1 and my_doc_2. But, each