Writing system docs & related training material


Work Samples (Diagrams): Process Flow Diagram Sample 1, Sample 2, Sample 3

Work Samples (Technical and Conceptual Overviews): Identity Management and Person Maintenance in CSMART (PDF)

Primary Tools Used: Microsoft Office, SnagIt, Gimp, LibreOffice Draw, TestComplete.  Also used: Enterprise Architect, Share Point,  Team Foundation Server, SQL Server Management console

Dates: April 2011 to April 2012.

As part of the training team, I prepared system docs and user docs for a case management software being designed by an outside IT company (Sogeti)  for the City of Houston Municipal Court System. I interviewed software developers, testers, subject matter experts and business analysts for information. My deliverables included an installation guide,  5-7 page technical overviews on  selected topics, process flow maps and reference guides.  I also prepared a “freshman orientation” packet of introductory information for new developers and IT staff on the project.

I supported other instructional designers with various tasks. One important task was using TestComplete software to load data automatically into the software for classroom exercises. I wrote automation scripts, documented the process and worked closely with other trainers to estimate  data needs for future classes. I also assisted in the training of new trainers.

The backend technologies behind the software product being developed  were .net, Windows Presentation Foundation (WPF), SQL Server, Object-Relational Mapping (with Entities Framework), Onbase Enterprise Content Management as well as several internal systems for the City of Houston.

For managing my own deliverables, I used Share Point every day and DropBox for file syncing and backup.

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