Below are my notes and highlights from this session at Write The Docs Europe 2016 in Prague. This is part of a series I wrote during the conference. This is not meant to be transcriptions and may have missed points made during they talk. They solely reflect my interpretations of the talk.
Operations Technical Writing for Data Centers
by Joan Wendt
Operations technical writing encompasses documentation targeting people bring up equipment and technology in huge data centers. This is more than just racking a new machine. This is everything big and everything small. Yes, even every single screw, nut and bolt. Joan started us off with a video tour of a data center to give a sense of scale of the work.
The work is very specialized and both hard to hire for and hard to train for. There is typically a very long ramp up time to get started. This is true even for people transferring from the same role at another company. Because of the high level of confidentiality in how things are set up, it is generally not possible to. ‘t study ahead for the interview or your first day. This role remains relevant because company’s like Google are still innovating in these areas and constantly upgrading.
Joan’s experience with tech writing started with user docs. After 21 years she moved to platform writing to challenge herself and enter a new phase of her career.
What they document:
- construction site prep
- assembly of complex components
- installation
- testing
- maintenance
- repair
- decommissioning
As an example, if you worked for a utility company that laid conduit, you would be in the field documenting the process. This involves taking pictures, taking notes, listening to conversations and questions and asking your own questions. You need to document everything from how the hole is dug to how the welds are done. In a data center they document things like facility infrastructure (power, cooling, etc.) and cable routing and management.
Therefore they work on site and document, take photos, screenshots and code samples. She works with engineers from the beginning even with just CAD drawings. If the thing to be documented is small enough, they will go into a lab and do a proof of concept build to test out the process so she can draft a document. Drafts at this point typically involve a lot of photo editing to make simulate the full install.
Once the build is started she stands with an engineer and a foreman as they do the actual work. She will have them test her draft, if it is ready, while the engineer trains the foreman on the process. Afterward, she rushes to build a new draft and return to the field to test it with the audience. Then the doc is finished and published. At this point the component can be built at scale.
Just connecting two cables can require 19 detail steps.
How are the Docs structured
- mostly stepped procedures
- heavy on best practices, tips and gotchas
- value is measured in functional quality. Clarity trumps formatting,
prettiness and other standard technical writing practices
- text is concise to the point, often excluding definite an indefinite articles
- there are no superfluous introductory texts for procedures
- style guides are only for project specific terms and acronyms
- formatting is not a focus as the documents are only for internal audiences
Photos are the Killer Feature
Every step needs perfectly precise and detailed photographs. This typically means that there be photos that show a:
- bird’s eye view
- worm’s eye view
- the front
- the back
- the inside
- the outside
This means there is a lot of climbing, stooping, an contorting to fit into places to take a photo.
Often you have to ask an engineer or installer to undo and then redo a process so every step can be photographed.
If the process changes every following step must be rephotographed so that only the accepted, single, clean procedure is photographed. There can be no evidence of earlier missteps.
Challenges
A big challenge is that she has to be in the environment. This can mean going up 40 feet to a ceiling, riding a scissor lift, wearing harnesses, being tied to a piece of equipment with a safety line, wearing safety vests, steel toe boots, hard harts, etc. Sometimes it is easy and you just need anti static heel straps and an anti-static-smock.
The SMEs are often sharing tribal knowledge and have no idea how to think about answering questions. They say phrases that need to be teased out into knowledge.
Ultimately, these docs are critical. The projects being documented can cost hundreds of millions of dollars and safety failures can kill someone if they do something in a bad way.