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).