In a recent discussion thread on LinkedIn, someone asked for opinions about the job description for a vacancy for a “Programmer/Writer”. Was it possible they asked, for someone to be both a software programmer and a technical writer? Was it true that only someone who was a programmer could understand software well enough to write about it? Or was it a misunderstanding of the real role of the technical writer?
The “Programmer/Writer” job description is based on the premise that programmers and technical writers share the same approach to a software product. Some of the people who responded to the LinkedIn thread agreed with that sentiment, but others did not and neither do I.
The role of the software programmer is to design and build a product that meets a set of requirements within given constraints of time and budget. Therefore, the programmer’s natural focus is on the code, and on how the product actually works.
The role of the technical writer is to describe and explain how a product can be used by someone else to do their job. For people who use software products, the software is just a tool, like a pencil or a hammer, and they need to use it to do something else. That “something else” may be quite a sophisticated task, and so a technical writer does need to acquire some domain knowledge, be it in cardiology, geophysics, microelectronics, or any other discipline. Technical writers use information about the product and its capabilities, domain knowledge derived from interviewing or otherwise interacting with subject matter experts, and above all their knowledge of communication theory and practice to create information products that support the user in their use of the product. Their focus is not on the code, and not even on the product on its own, but on the product in the context of its use. This is a very different mindset from that of the programmer.
Some technical writers may benefit from an understanding of software coding, or from having been a programmer in an earlier role, just as they may benefit from any other type of domain knowledge. But I do not believe that an advanced knowledge of a particular domain should be a pre-requisite for a technical writer. Far more important is their understanding of how to communicate with their readers, and their understanding of how to help product users do their jobs.
It is possible that some people can be excellent programmers and be excellent technical writers. I would imagine it is far more common for someone to excel in one skill and not the other. To ask someone to fulfill both roles sounds to me like asking someone to become schizophrenic.
It is a matter of great regret to me that so many hiring managers, HR departments, and recruitment agencies do not understand the fundamental value that a technical writer can add to a project even without extensive pre-existing domain knowledge.
Interesting points.
You might be interested in a recent discussion from the other side of the fence: http://tiny.cc/FWSsC
David wrote: In a recent discussion thread on LinkedIn, someone asked for opinions about the job description for a vacancy for a “Programmer/Writer”.
Can you provide a link to the job posting in question?
I started out as a TW, and after 15 years (by which time I’d been a Pubs Manager for several years), I switched over to programming. Initially I went into programming because I needed better tools for my pubs work, and they did not exist, so I had to build them. In 8080 assembler.
When writing software docs, I think it’s important that a TW can at least *read* the code. I always asked for it, and almost always found problems in it, which I reported to the responsible engineer. Before I wrote about software, I wrote about other engineering projects (power plants, chemical process plants) and there too used the same info the engineers used, drawings and specs. I felt the TW needed to understand the item they were writing about on an engineering level, not just interview an engineer and make the words nice. So the writers I hired could all do that.
Now, after 34 years writing software, I no longer feel I am personally a good TW. Programming has spoiled me.
So the TWs I work with have final say over their own work. Indeed, we all need to bridge two worlds, both to communicate, and to design software that really serves our customers, who are, still, TWs.
I think that it is an advantage for tech writers to have some domain knowledge. Such knowledge helps you understand the “why” of the product you are documenting and so provide better context to the “how”.