I have spent most of my tech writing career working with product development teams in software and other hi-tech industries. It is what I enjoy doing. It's what I do best. And I have come to the conclusion that it's not the best place to be.
That conclusion may surprise other tech writers, and it did surprise me a little as well. Usually the discussions are about whether the tech writers should report to marketing, or to customer services, or to development. The general consensus is that being part of the development team is best because daily contact with engineers and developers helps tech writers understand the product features they need to explain. It's also a good place to be because the end-user documentation, like the product itself, is usually seen as a deliverable item.
Let's look at this question from a slightly different angle. Where do shared interests lie? Marketing are interested in pre-sales - getting new customers in. Customer services are interested in post-sales - keeping existing customers happy. Development are interested in engineering and in code.
Did you notice the subtle difference there? Development aren't really interested in customers. Of course, in general terms they want the company to have customers because they know that's where the money to pay their salaries comes from, but their day-to-day focus is not on customers. The tech writers' focus is on customers, or at least it should be. That's why we share so much affinity with usability and user experience people, and with training people. That's why we try to write end-user documentation that is about tasks people have to do, rather than about features the product can offer. That's why we don't really fit in to a development team.
Where would the ideal place for tech writers be? I'd say that we are part of the team that looks at customer needs and how they are met. That would be a team with a slightly wider viewpoint than the development team, and I would call them the product management team. (I know that "product management" in many organisations is a marketing function.) Product management would have the responsibility for delivering useful tools to customers, and those tools include products, task-based documentation, training, and support. Where this kind of product management team doesn't exist sticking around the development team is clearly the preferred option, but I'd say it's not ideal.
How to create a help API
1 day ago