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 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. As mentioned multiple times throughout this guide, successful build of any OpenPOWER Foundation document requires two things: The cloning of the Docs-Master project. The cloning of the specific documentation project into the same parent directory as the 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 hypothetical new project named my_project.

To create this structure, one would clone the Docs-Master project to get the Docs-Master directory and all its contents (shown above in green), clone the Docs-Template project to get the Docs-Template directory and all its contents (shown in blue), and clone my_project project to get the my_project directory and all its contents (shown in red). Among these projects, the most important directory and project is Docs-Master. Without this project and associated directory, no document will build. As depicted in the above figure, the Docs-Master directory must sit at a level equal to all other project directories. Details on how to install this project can be found in the section. 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 (found in the OpenPOWER Foundation Repository at http://openpowerfoundation.org/repo.openpowerfoundation.org/) used to control the OpenPOWER Foundation document builds where all other dependencies, supporting tools, and document build rules are defined. The Docs-Template project and directory are depicted in blue in the above figure. The top level of the project Docs-Template must be cloned into the same parent directory as the Docs-Master for Maven builds to complete successfully. At the top level of the Docs-Template project are a pom.xml referred to as the "Workgroup POM" and a single document directory (template). The "Workgroup POM" is a minimal POM file that locates the parent, "Master POM" in the Docs-Masterproject directory with a <relativePath> definition of ../Docs-Master/pom.xml. The document directory contains the unique files used to create the document. The two most important files in the Docs-Template/template directory(and in any project) are the pom.xml or "Document POM" which describes how to build the document and which points to the main document file, the bk_main.xml file. This book file 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 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 document directory has similar contents to Docs-Template/template -- a "Document POM" (pom.xml) and a "Main book file" (bk_main.xml).