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.