Wrote deployment setup manual for remote data centers

 

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.

 

Running a small ebook publishing company as a side business

(If you are looking to hire someone for editorial or ebook production, check out the rate sheet of services I offer.)

Technologies Used: XML Oxygen Editor 22, Docbook 5, MS Office, Docbook XSLT stylesheets, Gimp, Audacity,  Sony Vegas Pro 19

Samples: Personville Press Website, Author Website,

Dates: 8/2010 to present

References/TestimonialsJack Matthews (author)  , Amy Valentine (author)

Since 2010 I have run a small ebook publishing company called Personville Press. So far, Personville Press has published 14 ebooks and (as of Summer 2024) commitments to publish 3 more. I do this during my breaks between jobs and contracts, but I also work on these projects to a lesser degree when I am working full time. 

On the business side, I:

  • Negotiated publishing terms  with the author and wrote everything up in a legally enforceable contract.
  • Set up a (rudimentary) accounting system for tracking royalties and transferring payments to the author.
  • Created marketing strategy and identified potential audience for the product.
  • Wrote press releases, product descriptions and announcements for online stores,  blogs and social media.
  • Hired talent as needed for illustrations, actors, studio engineers.
  • Evaluated ebook distribution channels for  reach and revenue potential.
  • Set up a customer relationship management system using market data I have personally collected.  (In progress)

On the technical side, I:

  • Created a Docbook XML-based toolchain for producing ebooks.
  • Researched ebook standards and implementations from the different devices and distribution channels.
  • Wrote  simple XSLT customizations to optimize the ebook file and a CSS template appropriate for the ebook and device.
  • Produce book promotion sites based on WordPress.
  • Tested ebook templates for the major devices and ebook platforms.
  • Ran a promotional website for the author.
  • Set up a turnkey shopping cart solution for customers to buy digital files directly.

On the editorial side, I:

  • Selected and proposed material for the ebook.
  • Wrote prefaces and relevant supporting  material.
  • Queried author for clarifications  and offering editorial suggestions when appropriate.
  • Set up a workflow for editing and producing an ebook (Basically, MS Word –> Filtered HTML –> Docbook XML –> Epub files).
  • Proofed text thoroughly and submitted files and metadata to distribution channels.

On the multimedia side, I:

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