1. Utah Open Source Conference - 2008 Writing Books with Open Source Tools Paul W. Frields Jared Smith

2. Utah Open Source Conference - 2008 About Paul Paul W. Frields Fedora Project Leader

3. Utah Open Source Conference - 2008 Jared Smith Training Manager About Jared

4. Utah Open Source Conference - 2008 Outline We'll share some “best practices” What is DocBook? Documentation toolkits Publican

5. Utah Open Source Conference - 2008 What is DocBook? DocBook is a specification for technical documentation It defines a markup language for creating books, articles, etc.

6. Utah Open Source Conference - 2008 Sample DocBook Example How to write a book Johnny Author Chapter the First Let's begin with a story! Once upon a time in Utah, there was a great conference...

7. Utah Open Source Conference - 2008 Why DocBook? Plain text for easy revision control Tags that are human-readable Separation of the content from the presentation XML can be transformed into various other formats –LaTeX –HTML –PDF

8. Utah Open Source Conference - 2008 Which Tags Do I Use? There are plenty of complete books, articles, etc. in DocBook that you can use as a reference DocBook: The Definitive Guide http://www.docbook.org/tdg/ (or buy the O'Reilly book) Use the full potential of your editor –Some editors will show you valid tags

9. Utah Open Source Conference - 2008 Best Practice: XIncludes By using XIncludes, you can break your book up into smaller files –One file per chapter or section Also allows you to create different spins of your book –Simply include different sections

10. Utah Open Source Conference - 2008 Best Practice: Entities An entity lets you define a section of text once, and use it multiple times Often used for product names, or boilerplate text Make it easy to rebrand your documentation

11. Utah Open Source Conference - 2008 I Learned DocBook. Now What? Once you've written some DocBook, you can use some other XML tools to help you –xmllint to verify that your XML is both: Well-formed Valid –xsltproc to transform the XML from one format to another, using a stylesheets Convert from DocBook to HTML, for example –xmltidy for cleaning up the formatting

12. Utah Open Source Conference - 2008 Toolchains Toolchains are simple a collection of scripts that simplify the task of working on your book –Validate your DocBook code –Convert to various other formats –Help with translation

13. Utah Open Source Conference - 2008 Publican Publican is an toolchain for creating and working with DocBook Another Red Hat contribution to the Open Source community Makes it very simple to create HTML and PDF output from your DocBook text Fedora is using Publican for official docs Let's see a demo!

14. Utah Open Source Conference - 2008 Best Practice: Revision Control You can't afford not to learn to use revision control –Emailing around copies of word processor documents doesn't count –Commit emails are wonderful if working on a group project –Can also be used as a productivity gauge

15. Utah Open Source Conference - 2008 Questions? Paul W. Frields stickster@gmail.com stickster@gmail.com Jared Smith jared@jaredsmith.net