Employer: Enfold Systems 2007-10

Producing a 246 page technical book

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


Company Name: Enfold Systems, Houston, TX
Job: Technical Writer
Dates:  November 2007 to February 2009

Samples: Troubleshooting Checklist; Installation Guide/Tutorial

Enfold Systems is a well-known consulting company that specializes in an open-source content management system called Plone.  Over the years, it has released several important tools for customers wishing to deploy Plone in a Windows enterprise environment.  Because of the inherent complexity of Windows enterprise deployments, the number of support tickets increased even though the software itself worked fine.  I was hired to provide better documentation (both local and online) and specifically better troubleshooting documents so sysadmins who used the products on a daily basis could solve basic problems themselves.

I worked with talented python developers from three different continents and participated actively in weekly product teleconferences (often serving as a kind of user advocate).  In addition, I filed bugs, fixed documentation bugs assigned to me and offered  feedback to developers about how to make things more user-friendly. Because I was documenting products under development, a fair part of my job involved setting up test situations to see the software in action.

An important part of my job was quality control: checking grammar and grammar, making sure URLs worked correctly and checking things in different browsers and operating systems.

Writing manuals for clients

Tools used: Microsoft Office, Gimp Graphics

A recent employer (Enfold Systems) provided consulting services for web site management. My role was to produce end user manuals for individual clients to document advanced system administration tasks. These manuals were narrow in scope and needed to be completed within a defined period of time (usually less than a week).  Deliverables were usually 10+ pages and given to clients in PDF format.

Topics included:

  • configuring  a proxy and load-balancing solution on  Linux using open source software (Apache, Varnish, Plone).
  • setting up and maintaining a wiki, with usage & usability tips.
  • backup and disaster recovery in the event of hardware failure
  • other Windows system administration tasks: site migration, performance monitoring, user management.

Producing Instructional Web Demos

Tools Used: Adobe Captivate 3, Audacity, Gimp

Samples: See the Screencast Page

Screencasts  are effective ways to walk users and customers through configuration and daily use of software.  In many cases, they can convey the series of steps for configuring something more easily than a page of written documentation.

At Enfold, I prepared two different kinds of screencasts.

First,  I prepared two in-depth tutorials about how to use Enfold Proxy (an integration tool for Windows System Administrators).   The product itself had a good interface and was easy to use, but many system administrators  had problems with the underlying concepts of how Internet Information Services (IIS) worked with web applications.  To address this I prepared a tutorial screencast which covered the core concepts of how to deploy a Plone web site on IIS.    A second in-depth tutorial  covered  advanced topics about how to integrate different kinds of web content inside the same host on an IIS site.

Work Involved: These in-depth tutorial screencasts were several minutes long  and included audio.   I identified   a learning objective, created  learning scenarios,  wrote a script,  recorded animation with Captivate, edited audio with Audacity, synchronized   audio with slides and corrected continuity errors.

I also produced several simple screencasts without audio. These screencasts were used to demonstrate how to perform simple tasks in a content management system called Plone. Some  were shown at product demonstrations to clients. The goal was simply to show how Plone  focused on accomplishing simple tasks within the content management system.