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

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.

Company Name: Texas Instruments, Houston, TX
Job: Technical Writer
Dates: August 2002-February 2006

LinkedIn Testimonial: Project Manager Dana Smith

Introduction: Digital signal processors (DSPs) are the little chips in cellphones, wifi card, HDTVs and digital cameras that convert analog signal to digital signals (and vice versa). Texas Instruments is the #1 seller of DSPs worldwide, and one reason customers prefer a TI solution is that TI’s software development kit includes a number of powerful software tools.

During the years I worked at Texas Instruments, the most important development tool was a mature full-featured GUI software tool named Code Composer Studio Integrated Development Environment (which was included in every development kit). Code Composer Studio IDE was a Windows-based tool with a major release generally every two years and minor releases every six months. In fact, new features were being added continuously to Code Composer Studio and often introduced for individual hardware platforms. Writing documentation for CCS was a team-effort; although I probably “owned the project” more than anyone in my group, other writers in our group provided key components to it.

My task/challenge was to manage this chaos! I managed the main project, which consisted of about a dozen smaller subprojects. When I started at TI, the help project (if you combined everything) already consisted of several thousand help topics. I had to maintain the documentation and add new help topics when needed.

See also: more detail about my TI work projects and writing samples from TI and other companies.

End User/Intended Audience: new customers & existing customers wishing to upgrade.

During my work at TI, I produced two “What’s New” guides. These were 8-10 page documents that were released on the website whenever there was a major release.

• Code Composer Studio IDE Getting Started, v. 3.1 (PDF)
  
• Code Composer Studio IDE Getting Started, v. 3.2 (PDF)
  

These two documents provide a user-friendly view of the new features in the new software product. The aim was to make a persuasive case for upgrading.

To obtain the information for these documents, I used existing online help which I created (along with other team members) during the early phases of product development. Later, I worked with the product’s marketing team to figure out which features to emphasize and how they would benefits to the user. I drafted the original document but amended it several times during the draft phase to incorporate suggestions from reviewers.

Tools used: Initially, we used an in-house Unix-based content management system to generate PDFs. Later, my company started migrating all their documentary repositories to be XML-based, so for the second one I used the XMetal XML editor to produce structured XML content (using an in-house DTD) which later was transformed by the Astoria XML document repository into PDF content.