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.

Tools Used: Email, Net Meeting, WebEx, Notetab Pro text editor, Wikipedia (!), knowledge bases, Gimp graphics program, screencapture programs
Writing Samples: Screenshot #1, Screenshot #2 (and other writing samples).

A technical writer’s primary job is to document new procedures or product features. Whenever the hardware people at Texas Instruments brought out the next generation of digital signal processors (DSP), the DSP programming software had to be enhanced to help engineers use those features. That meant I (and the other people on my team) had to learn about new features and to incorporate them into existing documentation.

How does one do this? This task can be broken down into several smaller ones:

1. Learn exactly what features were new. (Believe it or not, this was often difficult to ascertain)!
2. Attend meetings and look over project specifications and requirements documents.
3. Identify people who would be suitable subject matter experts (SMEs)
4. Arrange for SW demos when possible.
5. Determine whether I should write the documentation from scratch or request a SME to write a rough draft.
6. Determine which aspect to the new technology needed documenting and which aspects didn’t.
7. Provide a scope & schedule to the product manager.

Here are some of the challenges I faced:  (both at Texas Instruments and my other jobs)>

Writing for highly-skilled professionals. By definition, technical writers know significantly less about a subject than product designers (and often even end users). It’s easy for technical writers to fall into the trap of writing from the technical writer’s point of view instead of the end user’s point of view. To avoid this, the writer should avoid getting bogged down by introductory information they had to learn themselves and instead concentrate on things specific to the company’s tool which might be immediately useful to engineers. Conversely, when writing documentation for the general user, it is easy for the technical writer to get too technical or too detailed. Part of the art of technical documentation is knowing the right amount of detail to convey depending on the user.
Using the subject matter expert’s time effectively. For example, when do you call and when do you send email? And when should you try to learn things on your own? Experience has taught me that engineers often have competing priorities. Documentation can in fact be a low priority for an engineer! For my TI projects, I had to communicate with engineers on three separate continents. Developing a tolerance for delays is necessary; often if you multitask, you can switch gears and work on other tasks while you’re waiting.
Doing your homework. To receive good information, you have to ask smart questions. In other words, you have to ask questions and then follow up questions as well. Uncovering what the engineer forgot to tell you requires diligence, patience and persistence. It is unwise and impractical to drown your subject matter expert in open-ended questions. Among the strategies I use: doing background research on the web, reading existing documention and project documents beforehand, forwarding a draft copy to the SME and wait for him/her to tear it apart, scheduling face-to-face meetings or telephone calls or Net Meetings when completely in the dark.
Staying in the loop. Junior technical writers have a hard time getting invited to meetings and being on the cc list for important discussions. I’ve learned the hard way that it’s better to get invited to too many meetings than too few.
Allowing sufficient time for review. Writing technical documents often requires the SME or a whole team to look over your documentation. At my TI job, sometimes new features were added at the last minute, or engineers didn’t have time to do a review. That was normal. Oddly, it’s possible to get too bogged down by the review process. If you send too many versions to engineers too many times, they become confused or not motivated enough to provide useful feedback.