From 3da73be5548c6368c817f466eb74a27e58a41961 Mon Sep 17 00:00:00 2001 From: Jeff Scheel Date: Tue, 16 Feb 2016 14:53:53 -0600 Subject: [PATCH] Interim doc push Starting major update of documentation technical content, but need to rework tree structure. Therefore, pushing up existing changes. They are not intented to be complete nor accurate yet. More to come. Signed-off-by: Jeff Scheel --- doc/template/bk_main.xml | 34 +++++++++++--- doc/template/sec_template_getting_started.xml | 20 ++++---- doc/template/sec_template_new_document.xml | 5 ++ doc/template/sec_template_policies.xml | 47 ++++++++++--------- 4 files changed, 70 insertions(+), 36 deletions(-) diff --git a/doc/template/bk_main.xml b/doc/template/bk_main.xml index 2482fbf..b3ef126 100644 --- a/doc/template/bk_main.xml +++ b/doc/template/bk_main.xml @@ -9,7 +9,7 @@ - Template Guide + Master Template Guide A quick start template @@ -17,14 +17,14 @@ - Firstname - Lastname + Jeff + Scheel - Email@domain + scheel@us.ibm.com - Company + IBM @@ -33,7 +33,7 @@ OpenPOWER Foundation - Revision 0.9 + Revision 0.9.1 OpenPOWER @@ -57,8 +57,28 @@ --> + + + 2016-01-25 + + + + Version 0.9.1: Technical and process updates. + + + + + + 2015-08-20 + + + + Version 0.9: Draft for format review with TSC. + + + + - 2014-09-03 diff --git a/doc/template/sec_template_getting_started.xml b/doc/template/sec_template_getting_started.xml index 721c042..d04285c 100644 --- a/doc/template/sec_template_getting_started.xml +++ b/doc/template/sec_template_getting_started.xml @@ -22,14 +22,14 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_getting_star 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 maven and git as follows: - $sudo apt-get install git -$sudo apt-get install maven + #apt-get install git +#apt-get install maven On RPM-based Linux operating systems (Fedora, RHEL, openSUSE, SLES), install maven and git as follows: - $sudo yum install git -$sudo yum install maven + #yum install git +#yum install maven On Mac OS X, use Macports to install maven and git as follows: - $sudo port install git -$sudo port install maven3 + #port install git +#port install maven3 or use Homebrew to install maven and git as follows: $brew install git $brew install maven @@ -48,9 +48,13 @@ xmlns:xlink="http://www.w3.org/1999/xlink" xml:id="section_template_getting_star
Creating accounts - All OpenPOWER project documentation is maintained in GitHub trees, public and private. To join the GitHub community, + 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, apply at https://github.com/join. - If you will be participating in private OpenPOWER Foundation trees, you will need to visit the OpenPOWER Foundation Members + The private trees are grouped in the OpenPOWER Foundation project at + https://github.com/OpenPOWERFoundation. + If you will be participating in private OpenPOWER Foundation trees, you will need to visit the OpenPOWER Foundation Members Area wiki to find administrators for the appropriate git tree. To learn more about using git, see the online article in GitHub Help, "Good Resources for Learning Git and GitHub." at diff --git a/doc/template/sec_template_new_document.xml b/doc/template/sec_template_new_document.xml index 5203f93..78c1ecb 100644 --- a/doc/template/sec_template_new_document.xml +++ b/doc/template/sec_template_new_document.xml @@ -48,6 +48,11 @@ Checking connectivity... done. $mkdir my_proj $cp -r template/* my_proj $ + + + Add the new project to the master POM.xml file. Using your editor, add the following lines + between the <modules> and the </modules> tags near the top of the file:my_proj +]]> Finally, make sure to add the new directory to the git repository. diff --git a/doc/template/sec_template_policies.xml b/doc/template/sec_template_policies.xml index 102ecb6..36c0b98 100644 --- a/doc/template/sec_template_policies.xml +++ b/doc/template/sec_template_policies.xml @@ -1,29 +1,34 @@
- Policies and conventions + Policies and conventions Most document style policies are established simply by using the template documentation framework. However, by applying some conventions to the document source structure, community members will be able to work across more documentation projects. The recommended documentation structure guidelines are as follows: - - - 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" - - - Chapters files should be named with the prefix "ch_". - - - Section and sub-section files should be named with the prefix "sec_". - - - Appendix files should be named with the prefix "app_". - - - Figures source and images should be placed in the figures sub-directory for the document. - - + + + 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" + + + Chapters files should be named with the prefix "ch_". + + + Section and sub-section files should be named with the prefix "sec_". + + + Appendix files should be named with the prefix "app_". + + + Figures source and images should be placed in the figures sub-directory for the document. + + + + In addition to documentation documentation structure, general community/project guidelines are as follows + + +