Creating a new document from scratch follows four simple steps: Before undertaking one of these activities, it may be helpful to read the section to learn the basics about the documentation project structure.

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 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 .

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'... 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. 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 .

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 .

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: If your project exits on GitHub in the OpenPOWER Foundation area and it contains a doc_template directory, then follow the directions in to use this document as a base. 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. Otherwise, the instructions in will clone and copy this document as a base.

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 doc_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 doc_template folder used to prime the project. Rename the doc_template document directory to something new like my_doc. To accomplish this, use the mv command:: $ mv doc_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 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: $ mkdir my_doc $ cp -r source_doc/*.* 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 ]]> 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 .

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 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'... 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/doc_dev_guide 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/doc_dev_guide/* 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. You are now ready to begin making updates to your new document. Continue with the next step in .

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 it may be changed. Simply work through each item, making updates as requested. In the pom.xml file, pick your settings for document work product type (<workProduct>, work flow status (<documentStatus>), and security (<security>) carefully. provides an overview of the process and details the various settings needed in the document core project files. If you still have questions after reading this section, consult with your Technical Steering Committee representative. In addition to the document settings, 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. In the book.xml file, you will find the following document unique values which you most likely want to change: <title> The main title of the document. This appears in the largest font at the top of the title page. <subtitle> The second title of the document. This title appears in a smaller font below the <title> on the title page. <realeaseinfo> The document version value. This value should take the form of "Revision V.R.M" as described in recommendation . When ready, build your new document using standard maven commands like this:$ cd my_project/my_doc $ mvn clean [INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building OpenPOWER Template Guide 1.0.0-SNAPSHOT [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- maven-clean-plugin:2.5:clean (default-clean) @ openpower-template-guide --- [INFO] Deleting ~/my_doc/my_proj/target [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 0.353s [INFO] Finished at: Wed Feb 25 12:54:47 CST 2015 [INFO] Final Memory: 3M/7M [INFO] ------------------------------------------------------------------------ $ mvn generate-sources [INFO] Scanning for projects... [INFO] [INFO] ------------------------------------------------------------------------ [INFO] Building OpenPOWER Template Guide 1.0.0-SNAPSHOT [INFO] ------------------------------------------------------------------------ [INFO] [INFO] --- openpowerdocs-maven-plugin:1.0.0:generate-webhelp (generate-webhelp) @ openpower-template-guide --- [INFO] Processing input file: bk_main.xml ... [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO] ------------------------------------------------------------------------ [INFO] Total time: 20.361s [INFO] Finished at: Wed Feb 25 12:55:15 CDT 2015 [INFO] Final Memory: 30M/390M [INFO] ------------------------------------------------------------------------ $ If all goes well, the new generated pdf should be available in target/docbkx/webhelp/<webhelpDirname>/<pdfFilenameBase>.pdf. For assistance correcting commmon build failures, see . 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 .

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 end of that file which appear as follows: ]]> Copying and modifying existing files from the template or other documents is a great way to get started. When creating whole new chapter or appendix files from scratch, the ch_example.xml and app_template.xml files may serve as excellent starting points. For XML examples of various document structures, please see and its supporting source files in this document. Online resources such as those listed in may also be helpful. When creating new files for the project, remember to use the git add <file name> command to add new files to the git tree.