Description
My name is Sam and I am the head of technical documentation department at Zodiac Interactive.
At Zodiac we create low-level software (we call it 'middleware') that runs inside cable TV set-top boxes. Most cable companies in North America use our products; most probably, your set-top box runs at least some code written by Zodiac.
Zodiac has R&D departments all over the world; my office is located in Novosibirsk, Russia – right in the center of Siberia (so yes, there is a big probability that your set-top box runs some code that was written in the midst of Siberian taiga)
Documentation department at our R&D center concentrates only on architectural documentation: our docs explain the design and architectural decisions of our software components to other teams and R&D centers all over the world . We don't document user interface, write client knowledge bases, or do UI copy. Our technical writers must be tech-savvy enough to understand the architectural peculiarities of complex multithreaded applications, must be able to read code in C++ and, above all, must have perfect written English – Zodiac is an American company, and we write all our docs in English, not Russian.
During the last 5 years our R&D center went from not having any documentarians at all to a team of 4 excellent and capable technical writers. We were able to set up effective processes of integrating documentation in overall development activities and find out good metrics for quality of architectural docs.
Documentation processes and documentation quality are frequent topics at Write the Docs, so I want to talk about more generic things: interviewing, assessing and hiring technical writers.
My talk will tackle the following questions:
- How hard is it to find a "highly technical" technical writer? (remember that our documentarians must read and understand C++ code)
- Is it possible to switch your non-documentarian team members to writing documentation full-time? Do developers make good technical writers? What about QA engineers? (our answer was no: it's better to hire new documentarians than to evolve existing team members into technical writers)
- Which one is easier: hiring a technically capable person and teaching them to write well, or hiring a person with good writing skills but no technical knowledge whatsoever and then training them on technical stuff? (we went with the second option)
- Assessing the candidates: what is the perfect pre-interview assignment test and is it OK if the typical candidate spends 10-14 days to complete it? Should your candidates write something that resembles your working docs, or some generic texts on complex topics are enough? (for example, we ask our candidates to explain SSL certificates to their math-savvy, but not-cryptographically-inclined uncle: private/public keys, digital signatures, chains of trust and so on)
- Interviewing candidates for a technical writer position: are interviews necessary at all? Can a good interview outweigh a bad assignment test? Can a bad interview spoil the impression after a good assignment test? What things should be asked during an interview?