6 ms·

I wish we would give tech writers and generally the art of writing more respect. My company is in the medical field so we have to produce a ton of documentation

I wish we would give tech writers and generally the art of writing more respect. My company is in the medical field so we have to produce a ton of documentation. Turns out most developers aren't good writers, don't really want to write and are very slow at writing. So we burn a lot of expensive engineering hours on writing bad-quality documents instead of hiring a few writers who could make sure things are in consistent style and filed correctly. I am 100% convinced this would be way cheaper and produce better quality.

kaycebasques 3y ago
> I wish we would give tech writers and generally the art of writing more respect. I started my technical writer career ~11 years ago. We seemed to get much less respect back then. Gotta hand it to Stripe for really helping everyone see how much docs can contribute to a company's success. I still hear lots of other technical writers struggling with lack-of-respect though so maybe it depends on the company and maybe I'm just personally more sure of myself now that I've been at it for a while. Also, thank you for respecting us! > So we burn a lot of expensive engineering hours on writing bad-quality documents instead of hiring a few writers who could make sure things are in consistent style and filed correctly. If you just need help with consistent style and filing correctly you might just need technical editors, not technical writers. I believe technical editors in general are a bit cheaper than technical writers, but I may be mistaken about that. Technical writers are much more involved in the overall creation and management of organizational knowledge. More on that after the next quote. > I am 100% convinced this would be way cheaper and produce better quality. We do consistently earn less than SWEs so yes, I think this is a pretty defensible argument to make. If you fall into the trap of thinking that you can offload all documentation work to technical writers, I would argue you might be making a very expensive mistake. The simple fact is that for any given domain there is a vast ocean of knowledge far bigger than the capacity of any technical writing team to document. We simply can't do it on our own, we always need the broader org contributing to the docs, too. The more complicated fact is that docs are intricately connected to knowledge sharing in general. Teams think they're just offloading docs but what ends up happening is that their own knowledge-sharing tools / habits / processes atrophy. And the tragedy is that they possess knowledge not found anywhere else in the org. So everything gets less efficient. There was a really interesting report that showed that high-quality docs correlate with above-average performance across an entire org. Unfortunately I don't think the report was presented compellingly but when you look at it in the light of "technical writers are shepherds of organizational knowledge" it makes a lot of sense and suggests the correlations are real: https://cloud.google.com/blog/products/devops-sre/deep-dive-into-2022-state-of-devops-report-on-documentation https://cloud.google.com/blog/products/devops-sre/deep-dive-... So ironically, if you work with a senior technical writer, you probably won't actually find yourself writing less docs. We'll just make it less painful / more straightforward and you'll be more motivated to write docs because we keep hammering home how docs are connected to the greater mission :D
- euroderf 3y ago
  > you'll be more motivated to write docs because we keep hammering home how docs are connected to the greater mission There is also the Leverage argument. A few hours spent on docu - if done right - will translate into hundreds (thousands? :) of hours saved by users AND by your own organisation's tech support. Any dev who is not totally self-absorbed will "get it", if you can convince them that the downstream pipeline is there to translate their implicit knowledge into explicit, accessible knowledge.
PartiallyTyped 3y ago
I currently work as a dev but have a more scientific background, and that background is leaking into my writing, so much so that I have been told that my documents are too abstract and "science-y". My more technical audience - principals + - are fine with it, but others struggle a lot. Unfortunately we don't have that technical writers, and I need to improve on this. I'd appreciate any and all recommendations.
euroderf 3y ago
Yes, hire a tech writer, who solicits developer brain dumps, and expands & translates them into docu for mere mortals. Value add. Happy developers may or may not learn to assist & speed this process by cranking out some Markdown when the mood hits them.

kaycebasques 3y ago

> I wish we would give tech writers and generally the art of writing more respect. I started my technical writer career ~11 years ago. We seemed to get much less respect back then. Gotta hand it to Stripe for really helping everyone see how much docs can contribute to a company's success. I still hear lots of other technical writers struggling with lack-of-respect though so maybe it depends on the company and maybe I'm just personally more sure of myself now that I've been at it for a while. Also, thank you for respecting us! > So we burn a lot of expensive engineering hours on writing bad-quality documents instead of hiring a few writers who could make sure things are in consistent style and filed correctly. If you just need help with consistent style and filing correctly you might just need technical editors, not technical writers. I believe technical editors in general are a bit cheaper than technical writers, but I may be mistaken about that. Technical writers are much more involved in the overall creation and management of organizational knowledge. More on that after the next quote. > I am 100% convinced this would be way cheaper and produce better quality. We do consistently earn less than SWEs so yes, I think this is a pretty defensible argument to make. If you fall into the trap of thinking that you can offload all documentation work to technical writers, I would argue you might be making a very expensive mistake. The simple fact is that for any given domain there is a vast ocean of knowledge far bigger than the capacity of any technical writing team to document. We simply can't do it on our own, we always need the broader org contributing to the docs, too. The more complicated fact is that docs are intricately connected to knowledge sharing in general. Teams think they're just offloading docs but what ends up happening is that their own knowledge-sharing tools / habits / processes atrophy. And the tragedy is that they possess knowledge not found anywhere else in the org. So everything gets less efficient. There was a really interesting report that showed that high-quality docs correlate with above-average performance across an entire org. Unfortunately I don't think the report was presented compellingly but when you look at it in the light of "technical writers are shepherds of organizational knowledge" it makes a lot of sense and suggests the correlations are real: https://cloud.google.com/blog/products/devops-sre/deep-dive-into-2022-state-of-devops-report-on-documentation https://cloud.google.com/blog/products/devops-sre/deep-dive-... So ironically, if you work with a senior technical writer, you probably won't actually find yourself writing less docs. We'll just make it less painful / more straightforward and you'll be more motivated to write docs because we keep hammering home how docs are connected to the greater mission :D

euroderf 3y ago
> you'll be more motivated to write docs because we keep hammering home how docs are connected to the greater mission There is also the Leverage argument. A few hours spent on docu - if done right - will translate into hundreds (thousands? :) of hours saved by users AND by your own organisation's tech support. Any dev who is not totally self-absorbed will "get it", if you can convince them that the downstream pipeline is there to translate their implicit knowledge into explicit, accessible knowledge.

PartiallyTyped 3y ago

I currently work as a dev but have a more scientific background, and that background is leaking into my writing, so much so that I have been told that my documents are too abstract and "science-y". My more technical audience - principals + - are fine with it, but others struggle a lot. Unfortunately we don't have that technical writers, and I need to improve on this. I'd appreciate any and all recommendations.

euroderf 3y ago

Yes, hire a tech writer, who solicits developer brain dumps, and expands & translates them into docu for mere mortals. Value add. Happy developers may or may not learn to assist & speed this process by cranking out some Markdown when the mood hits them.