4 ms·

The best technical documentation I’ve seen at a company was written by a technical writer. Most companies don’t like hearing this because it costs more than add

by teeray 7y ago

The best technical documentation I’ve seen at a company was written by a technical writer. Most companies don’t like hearing this because it costs more than adding an additional drag on your development teams to also become solid writers (good writing is real, time-consuming work). Having someone whose job it was to start from the perspective of your users, ask questions of the dev team along the way, and document the journey yielded enormously useful docs.

Ididntdothis 7y ago
I work in medical devices so we have to produce a ton of documentation in a very specific format. I never understood why our devs have to spend a ton of time on producing not very good documents. We have a few tech writers who produce much better work but they are completely overloaded. I don't understand why management doesn't hire more writers to free up the devs and also to produce better docs faster.
- jnxx 7y ago
  I guess that not everything which is required is helpful at all for the actual developers, is it?
  - Ididntdothis 7y ago
    The content may be useful but there is a lot of regulation what to document when and to what level. That knowledge is not very useful for devs.
jnxx 7y ago
As a scientist by education, I have learned to write on scientific technical stuff and it was a long, time-consuming and sometimes painful process - but ultimately, I like to write, and I like to produce clear written information. What was most difficult for me was to overcome perfectionism, which totally blocked me when I tried to write my first peer-reviewed paper. I learned a lot from a few very good books on writing. The very best I found so far is this one: Effective Writing for Engineers, Managers, Scientists, by H.J. Tichy. https://www.amazon.com/Effective-Writing-Engineers-Managers-Scientists/dp/0471807087/ref=sr_1_1?keywords=writing+for+engineers+and+scientists+Tichy&qid=1567950088&s=gateway&sr=8-1 https://www.amazon.com/Effective-Writing-Engineers-Managers-... It was fantastic for me because it describes writing as an iterative process with subsequent rounds of structuring and refinement, and that helped me to overcome blocks. I learned also a lot on how to make my writing more concise and to the point. For a scientist and programmer, it is really essential that one does not simply assumes that one already knows how to do it! For me, it is way more difficult than it looks - but also way more satisfying than I thought, when it is finished. I agree that this is not for everyone, because it needs to be learned, is hard to learn, and is a very different set of skills to coding. And there is clearly a field of work for specialists. One lesson learned that I took away from this is that writing is a separate task, and it is difficult to do it at the same time as producing code. But back to the main topic. As a documentation writer under time constraints, what could I do to find out what the not-yet-present reader of the documentation might need to know?

by teeray 7y ago

Ididntdothis 7y ago

I work in medical devices so we have to produce a ton of documentation in a very specific format. I never understood why our devs have to spend a ton of time on producing not very good documents. We have a few tech writers who produce much better work but they are completely overloaded. I don't understand why management doesn't hire more writers to free up the devs and also to produce better docs faster.

jnxx 7y ago
I guess that not everything which is required is helpful at all for the actual developers, is it?
- Ididntdothis 7y ago
  The content may be useful but there is a lot of regulation what to document when and to what level. That knowledge is not very useful for devs.

jnxx 7y ago

As a scientist by education, I have learned to write on scientific technical stuff and it was a long, time-consuming and sometimes painful process - but ultimately, I like to write, and I like to produce clear written information. What was most difficult for me was to overcome perfectionism, which totally blocked me when I tried to write my first peer-reviewed paper. I learned a lot from a few very good books on writing. The very best I found so far is this one: Effective Writing for Engineers, Managers, Scientists, by H.J. Tichy. https://www.amazon.com/Effective-Writing-Engineers-Managers-Scientists/dp/0471807087/ref=sr_1_1?keywords=writing+for+engineers+and+scientists+Tichy&qid=1567950088&s=gateway&sr=8-1 https://www.amazon.com/Effective-Writing-Engineers-Managers-... It was fantastic for me because it describes writing as an iterative process with subsequent rounds of structuring and refinement, and that helped me to overcome blocks. I learned also a lot on how to make my writing more concise and to the point. For a scientist and programmer, it is really essential that one does not simply assumes that one already knows how to do it! For me, it is way more difficult than it looks - but also way more satisfying than I thought, when it is finished. I agree that this is not for everyone, because it needs to be learned, is hard to learn, and is a very different set of skills to coding. And there is clearly a field of work for specialists. One lesson learned that I took away from this is that writing is a separate task, and it is difficult to do it at the same time as producing code. But back to the main topic. As a documentation writer under time constraints, what could I do to find out what the not-yet-present reader of the documentation might need to know?