Open Source for Open Documentation: Developing ... · Jeff Scheel, Technical Steering Committee...
10
Jeff Scheel, Technical Steering Committee Chair IBM Distinguished Engineer, Cognitive Software Strategy Join the Conversation #OpenPOWERSummit Open Source for Open Documentation: Developing Documentation for the OpenPOWER Foundation
Transcript of Open Source for Open Documentation: Developing ... · Jeff Scheel, Technical Steering Committee...
Jeff Scheel, Technical Steering Committee ChairIBM Distinguished Engineer, Cognitive Software Strategy
Join the Conversation #OpenPOWERSummit
Open Source for Open Documentation: Developing Documentation for the OpenPOWER Foundation
© 2018 OpenPOWER Foundation
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/
© 2018 OpenPOWER Foundation
Documentation Development Guide
Documentation Development Guide
© 2018 OpenPOWER Foundation
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
© 2018 OpenPOWER Foundation
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
© 2018 OpenPOWER Foundation
OpenPOWER Doc. Development build Building Doc. Dev. Guide:
1.Clone Master Document project: git clone https://github.com/OpenPOWERFoundation/Docs-Master
2.Clone Doc. Dev. guide project:git clone https://github.com/OpenPOWERFoundation/Docs-Template
3.Change to working directory:cd Docs-Template/template
4.Build with Maven:mvn generate-sources
5.Locate generated files:cd target/docbkx/webhelp/<project> 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 ...snip...[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 ...snip...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
© 2018 OpenPOWER Foundation
OpenPOWER Doc. Development Guide sampleDocbook tag-based development See Chapter 2 for examples
© 2018 OpenPOWER Foundation
Other OpenPOWER documents Many additional projects (private)
• OpenPOWER Foundation GitHub repositories https://github.com/OpenPOWERFoundation
• Contact Jeff Scheel ([email protected]) for access
© 2018 OpenPOWER Foundation
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)
© 2018 OpenPOWER Foundation
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?
