Technologies Used: MS Office 2013, Visio, SnagIt, XML Oxygen Editor, Docbook

Samples: (Confidential;  screenshots )

Dates: 5/2014 to 7/2014

An enterprise cloud hosting service wanted to standardize the way it set up data centers overseas.  It needed me to do two things: 1)prepare a detailed deployment doc for “Remote Hands” at IT centers in one country (Singapore), and  2)prepare a  template to make it easier to append documents in this manual and edit things easily.

The employer didn’t want to use MS Word because it is difficult to do version control and manage the document (and template) over time. Also, MS Word was unwieldy for handling lots of tables and information heavy with data and graphics.  It was decided to produce the document in Docbook XML and use the Docbook XSLT stylesheet to produce a simple-but-functional PDF. Because the remote hands were likely to know English as a second language, the information had to emphasize  illustrations and use very basic vocabulary. It had to have comprehensive instructions but also be easy to find things.

The deployment document needed to show the correct layout of a server rack and the proper cabling and network connections to ensure a perfect configuration. It was not necessary to document the application layer (or even the networking layer) because once the cabling was correctly set up and connected, network engineers from Houston could start and manage the devices (and the apps running on them). Remote hands would be unboxing new devices and configuring them quickly.  Therefore, the most important things to document were:

1. identifying hardware and their proper position on the server rack (by using grid numbers and letters).
2. identifying the ports on each piece of hardware on both the front and back.
3. identify the function of different  cables and which ports they needed to be associated with
4.  how to look up which cable needed to be connected to a specific source port, and where its destination port ought to be.
5. Identifying the optimal sequence of cabling and how to check your work.

To find the information, I had to interview 2 network engineers (luckily in Houston) and look up specs for each network appliance on the web. Also, I had to choose photos of hardware which were easy to understand and in some cases create original graphics when none were available. I imported  premade  graphic elements of server components into my Visio diagrams and labeled everything correctly.

The biggest challenges of this contract were

1. documenting cabling of devices which I never had physical access to. Each component  cost $10,000+ and up, so I relied mainly  on product specs and photographs taken of server racks from previous deployment.
2. verifying the accuracy of all instructions. It was easy for a hired hand to plug a cable in the wrong place, and also it was easy for a technical writer to type in a wrong number (especially when the network engineers changed the deployment instructions several times). Therefore, I had to use various methods to doublecheck the data and ensure that the final data tables were consistent with what the engineers wanted.
3. Understanding what kind of information the remote hands needed and how they would be viewing the manual. I had to consider the various possible ways the pages could be read and what kinds of presentation would be easier for remote hands to understand. In many cases, eliminating unnecessary verbiage was essential in favor of  tabular data and graphics.
4. Using advanced features of  Docbook XML. I had to use informative captions, width-appropriate tables, and size graphics appropriately. I also used sidebars for warnings and long numbered lists. I already was an expert on using Docbook. But I had to optimize and customize  the XML, graphics and XSLT for this specific project.
5. Because this was a one-time contract project, I also prepared a guide for adding/editing Docbook documents and projects for anyone editing the document in the future.

The resulting 48 page manual was succinct, thorough and easy to read. I provided easy- to-read multicolored  labels for both photographs and diagrams.

Technologies Used: Visio, SnagIt, Personal Brain mind-mapping software, Exchange 2003 & 2010, Remote Desktop, Google Postini, Active Directory, ActiveSync, Outlook Web Application (OWA), Sharepoint, Windows Server 2003

Dates: 9/2012 to 11/2012

Samples:  (Confidential, but I might be able to reveal short excerpts of these docs in person).

An IT company hired me to document email architecture for a major international media company.  This media company had three administrative groups for running Exchange in 3 different data centers. Two were running Exchange 2010, and  one was running Exchange 2003. But  all administrative groups shared Active Directory  Resource to allow all users and distribution lists. The media company used public folders, ActiveSync and OWA; the Exchange 2003 data center (which I documented most thoroughly) used clusters and Storage Groups on Storage Area Networks (SANs); it also ran servers for  message archiving, web proxying, faxing, Blackberry,  business continuity and antivirus. It also used Postini (a Google Enterprise app) for  email security.

The Exchange 2003 data center  was constantly experiencing  outages and needing to implement stopgap fixes. Also, the media company lacked any documentation of what the current system was like (because a key Administrator had recently left).  My job was to talk to  current Exchange administrators and outside Exchange experts to write a 12 page technical white paper recommending short and long term solutions to upper management. I also wrote a 25 page Technical Design Document which documented all major system components of the 2003 data center plus all the configuration settings for the Exchange bridgehead/frontend/servers, system policies, connectors and message formats.

An important part of my job was producing system architecture diagrams  to illustrate the ways that different components interacted with one another. These diagrams  could be used as quick references by management and support staff to understand the implications of any proposed action.

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