open source for open documentation: developing ... · open source for open documentation:...

Open Source for Open Documentation: Developing Documentation for the OpenPOWER Foundation

Jeff Scheel, IBM Distinguished Engineer, Chair System SW Work Group

Join the Conversation #OpenPOWERSummit

© 2018 OpenPOWER Foundation2

The Resource Catalog

Generalized library capability for eco-system content

Categorization and search user interface

WG Specifications and Notes Product information Solution information

http://openpowerfoundation.org/technical/resource-catalog/


Documentation Development Guide

Documentation Development Guide


OpenPOWER Documentation Development XML text source with docbook tags• Github repositories for collaborative document development• Maven processing to generate web ready html and pdf documents• OpenSource tooling usable on Linux, Mac OS, Windows


OpenPOWER Doc. Development Guide source Public source:

• GitHub common pages: https://github.com/OpenPOWERFoundation/Docs-Master

• Github Document Development guide project: https://github.com/OpenPOWERFoundation/Docs-Template


OpenPOWER Doc. Development build Building Doc. Dev. Guide: Clone Master Document project:

1.git clone https://github.com/OpenPOWERFoundation/Docs-Master

2.Clone Doc. Dev. guide project:3.git clone

https://github.com/OpenPOWERFoundation/Docs-Template

4.Change to working directory:5.cd Docs-Template/template6.Build with Maven:7.mvn generate-sources8.Locate generated files:9.cd target/docbkx/webhelp/<project>10.11.where <project> name varies

scheel@goags:~/mydocs$ git clone https://github.com/OpenPOWERFoundation/Docs-MasterCloning into 'Docs-Master'...remote: Counting objects: 72, done.remote: Total 72 (delta 0), reused 0 (delta 0), pack-reused 72Unpacking objects: 100% (72/72), done.Checking connectivity... done.scheel@goags:~/mydocs$ lsDocs-Masterscheel@goags:~/mydocs$ git clone https://github.com/OpenPOWERFoundation/Docs-TemplateCloning into 'Docs-Template'...remote: Counting objects: 253, done.remote: Total 253 (delta 0), reused 0 (delta 0), pack-reused 253Receiving objects: 100% (253/253), 468.94 KiB | 0 bytes/s, done.Resolving deltas: 100% (151/151), done.Checking connectivity... done.scheel@goags:~/mydocs$ lsDocs-Master Docs-Templatescheel@goags:~/mydocs$ cd Docs-Template/template/scheel@goags:~/mydocs/Docs-Template/template$ mvn generate-sources[INFO] Scanning for projects...[INFO] [INFO] ------------------------------------------------------------------------[INFO] Building Documentation Development Guide 1.0.0-SNAPSHOT[INFO] ------------------------------------------------------------------------[INFO] [INFO] --- openpowerdocs-maven-plugin:1.1.0:generate-webhelp (generate-webhelp) @ openpower-template-guide ---[INFO] Processing input file: bk_main.xml[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojo[WARNING] Property not found in com.agilejava.docbkx.maven.DocbkxWebhelpMojoFeb 27, 2018 11:43:28 AM org.apache.fop.apps.FopFactoryConfigurator configureINFO: Default page-height set to: 11inFeb 27, 2018 11:43:28 AM org.apache.fop.apps.FopFactoryConfigurator configure ...[INFO] Applying customization parameters

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">Parsing: /home/scheel/mydocs/Docs-Template/template/target/docbkx/webhelp/doc-devel-guide/content/section_cloning_project.html ...The created index files are located in /home/scheel/mydocs/Docs-Template/template/target/docbkx/webhelp/doc-devel-guide/content/search/.js[INFO] See /home/scheel/mydocs/Docs-Template/template/target/docbkx/webhelp/bk_main for generated file(s)[INFO] ------------------------------------------------------------------------[INFO] BUILD SUCCESS[INFO] ------------------------------------------------------------------------[INFO] Total time: 31.547 s[INFO] Finished at: 2018-02-27T11:43:45-06:00[INFO] Final Memory: 83M/729M[INFO] ------------------------------------------------------------------------scheel@goags:~/mydocs/Docs-Template/template$ cd target/docbkx/webhelp/doc-devel-guide/scheel@goags:~/mydocs/Docs-Template/template/target/docbkx/webhelp/doc-devel-guide$ lsbookinfo.xml common content doc-devel-guide-20180227.pdf favicon.ico index.html webapp


OpenPOWER Doc. Development Guide sampleDocbook tag-based development See Chapter 2 for examples


Other OpenPOWER documents Many additional projects (private)

• OpenPOWER Foundation GitHub repositories https://github.com/OpenPOWERFoundation

• Contact Jeff Scheel ([email protected]) for access


Addition information Documentation Development Guide also

addresses Installing open source tools

• (1.1.1 Installing tools)• A deeper description of project structure • (1.2 Understanding the project structure)• Step-by-step description of creating documents • (1.3 Creating a new document)• Tips for debugging build failures • (1.5 Debugging build failures)• An explanation of the OpenPOWER Foundation

Documentation process • (1.6 Publishing OpenPOWER Documents)• Samples of common DocBook tags • (2 Documentation examples)


Final thoughts

OpenPOWER Foundation is building open source documentation using open tools – GitHub, DocBook, Apach fo, Maven

The OpenPOWER Foundation Documentation Development Guide details how to build, create, and publish documents

This process/environment has provided professional looking, maintainable documents in PDF and HTML form. See the Resource Catalog.

Let us know if you would like to participate

Questions?