I write technical documentation, heuristic reviews and terrible puns.
Hardware installation guide
I was commissioned to write a quick start guide detailing how to install server hardware (referred to as an "appliance" from here on out) into a standard data centre rack. Here is an outline of the process, and excepts of my work.
How I did it
Here are the key processes I followed in order to write this hardware installation guide.
1. Video review and engineer notes review
As client was located on a separate continent, their engineers recorded video of themselves installing the server hardware into a rack, for me to review and use as a basis for the initial draft.
​
I also received a series of notes the engineers maintained for themselves, which dot-pointed useful information including:
-
port names,
-
the meanings for various status light indicators, and
-
notes on how to orient the appliance when inserting into a rack.
2. Initial draft
After consulting with the engineers via remote meetings to clarify any questions, I divided the guide into the following sections:
​
-
Installation site requirements: required aspects of the data centre hosting the racked appliance.
-
Racking requirements: the required rack width, spacing and power.
-
Unboxing: what clients should expect to find within each shipped appliance's box.
-
Preparing the appliance for storage caddy installation.
-
Installing the storage caddies.
-
Racking the appliance. (And how to safely remove from a rack.)
-
Cabling the appliance.
I wrote the initial instructions, and then created line art from the video demonstration stills, to help guide the designers when they produced the final diagrams.
​
Example "line art" from video still:​
​
And here's the final version of the image provided by the client's graphic designer:
3. Fact checking with internal subject matter experts (SMEs)
After the initial draft was completed, I ran through the document with a lead engineer and the operations director for the company. This helped to identify any additional edits required to ensure that there were no gaps in the documentation.
​
I made minor adjustments based on this feedback, and then the document was used in the field by a new company employee to test how easy the instructions were to follow.
4. Design process
Once all text had received final approval, I worked alongside the client's graphic designer to produce the final designed document that would be printed and shipped out to customers with their new appliances. I acted as the main point of contact for the designer when they had questions about the hardware installation process.
Results
My client's customers were now able to perform additional basic maintenance procedures without the need for my client to perform an onsite visit.
“[Wendy's] ability to translate complex technical concepts into clear, concise, and accessible content for a variety of audiences has been a great asset to SoftIron.”
Kenneth Van Alstyne, Chief Technology Officer