Technologies Used: XML Oxygen Author, Docbook 5, SnagIt, Subversion, XEP PDF Processor, Personal Brain mindmap software, iAnnotate PDF, Visio
Samples: Here and Here. (More available upon request).
Linkedin Testimonial: CEO Alan Runyan
Dates: 2/2010 to 9/2010; 2013. 2nd Revised edition from 5/2013 to 10/2013.
I wrote a 246 page technical book User’s Guide to Plone 4. It was a total rewrite of the prior edition (which I helped to edit). For the Plone 4 edition, I wrote 100% of the content (including the interior artwork, layout, glossary and index). Besides the cover art and technical review, I did the planning, formatting and organization of the content, plus most of the editing. I did it as a work-for-hire with my previous employer, and provided camera-ready copy to Amazon’s Createspace for print publication. (A PDF version is also for sale at a reduced price). The target audience was the beginning/intermediate end user for Plone, an open source content management system.
I wrote the content entirely in an XML language for publishing called Docbook 5. I wrote an XSLT customization layer that used the XSL-FO Docbook stylesheets for producing a PDF. In this customization layer, I specified layout features, title page features, font defaults and simple XSLT transformations to make the content presentable. I used the XEP PDF processor from RenderX. Using the SnagIt tool, I made print-ready screenshots and did light editing of graphics for it. Through experimentation, I devised a method and minimum requirements for producing graphics. Using diagrams I also created original diagrams to illustrate workflow states in the Plone content management system. Also, I had to import a small amount of information from the previous edition which was produced using LaTex.
The subject of the book was already something I was relatively familiar with. I’d written Plone documentation for Enfold for 2 years, but for this project, I had to identify newbie issues and explain lots of areas that typically give problems to end users. Plone 4 was a major version change with new features, and my company’s goal was for the book’s release to coincide approximately with the release of the software. During the writing of the book, I was working with “beta software” and had to deal with numerous bugs, interface idiosyncrasies and things which had never been documented. To gather information, I did a lot of testing on my own, but I followed developer mailing lists and user forums for information. During the whole process, I filed about a dozen bugs with the software project.
Here are some details about the overall production process:
- Outlining and Information Gathering using Personal Brain mindmapping software. I chose chapter subjects after extensive discussion with Enfold staff.
- Regular checkins into a subversion repository using Tortoise SVN.
- Although I worked mainly from home, I gave project reports weekly with Enfold managers.
- We did project tracking using a customized version of JIRA. I assigned questions and tasks to Enfold developers, and Enfold people assigned tasks and bugs to me. Technical review & editing were managed 100% on JIRA.
- I used Oxygen XML Author to author the XML directly. Even though it supports a WYSIWIG view, I decided to use iPad’s iAnnotate app to do proofreading and edits directly on the PDF (which I would later transfer to the XML).
