Ongoing
Technical Writer
Chris Hanaoka (Tech Director)
Ian Childress (Tech Lead)
Mike Sahari (Developer)
Ryan Halloran (Developer)
Joshua Sera (Technical Writer)
Polyverse's Polymorphing is a cybersecurity product. It protects against buffer overflow attacks by scrambling an operating system's binaries to make it almost impossible for attackers to inject malicious code into predictable places. Part of why Polymorphing works is because the cost of re-scrambling binaries is relatively low, while the cost of finding an exploit in any given binary is high. This implies that you need a build farm that's just dedicated to recompiling and rescrambling an operating system's binaries on a regular basis.
Eventually Polyverse started selling its build farm as a separate product. My job was to write an installation and operations manual for it, so professional services engineers would have a document to use for installation, and customers would have a document to refer to for everyday use.
The target audience was Polyverse's professional services engineers, and customers who already understand Polymorphing's value proposition. The taget audience would already have a reasonable understanding of AWS, since the build farm is written on AWS's infrastructure.
- First, I needed to find out what the engineers needed out of the documentation.
Professional services engineers would primarily need the document to fully explain the installation process. The subject matter experts in this case were the engineers working on the build farm, and I immediately knew, since they were intimately familiar with the product, I'd need to be able to test the documentation extensively to make sure all steps were represented. Often experts will gloss over steps that inexperienced users wouldn't know about. The first step in this was making sure we had a way to return all services to a blank slate, so we could use the documentation to guide us through installation, and reset if a step was wrong, missing, or anything else went wrong.
- Next, I needed to find out what management needed out of the documentation.
Management is primarily concerned with customer satisfaction. Technology can behave unpredictably sometimes. The most important thing from a customer's point of view is knowing that support is available quickly, and that problems are solvable quickly. I'd be providing part of that support just by handling emails and being customer facing, but part of the research was also asking the engineers and management what sorts of things have gone wrong in the past. Providing a troubleshooting section in this case would help customers to solve their own problems, and support contact information would help when they had a problem they couldn't solve.
- Finally, I needed to research what concepts people would have the most trouble with. Specifically, people new to the product.
I did this by interviewing new hires, both at the management level, and sales people. Sales people would need to explain concepts to customers, and finding out what they struggled with was very informative.
First, I interviewed the subject matter experts in order to get an idea of the high level steps involved in an installation. I recorded each interview, then used the recording to take notes.
From this, I created an outline for the document:
What problems the build farm solves for, why it's built the way it is.
Installing the build farm on AWS
The UI for day-to-day operations
Installing what the build farm builds on client machines
Keeping AWS costs down
Troubleshooting, common questions
I went through every process described in the manual, and took screenshots of each step. Afterwards, I reviewed the process with an engineer, and got sign-off for that section.
Finally, I sent a copy of the full document to the entire team. I gathered feedback and made edits when necessary.
The most important testing step was just to go through the document with an engineer, from a clean slate, and make sure every step was documented. On several occasions, we found that a step had been missed, and that we needed to include either that step, or troubleshooting instructions if something went wrong. If a test run went wrong, I'd go back, and make changes to the document, and the engineer would reset the hardware to a clean state. Once the changes had been made, we'd start the whole process over again from step 1. The document was only considered correct once the entire installation process was completed without problems.
Finally, after a final edit pass with the engineering team and marketing, the document was ready for release.
The US Navy successfully installed the Build Farm for use with CentOS installations. The documentation I wrote was used as a selling point.
Documentation can fall out of date, so regular reviews and changes are required. In this case, since we were heavily reliant on AWS, bi-monthly reviews of the AWS UI was required to make sure screenshots would stay current.
The second concern is keeping track of customer feedback. Any problems or complaints from customers would need to be collected and used to make changes to the document, also on a bi-monthly basis.
If you'd like to see the documentation, Email me, and I'll be happy to provide a copy.