4 ms·

Any ideas on how to help my engineer colleagues write good documentation that actually helps? Most of the problems that I see come from a lack of empathy - they

Any ideas on how to help my engineer colleagues write good documentation that actually helps? Most of the problems that I see come from a lack of empathy - they assume the reader has previous knowledge about things that are only inside their head, so after reading the docs there's always the need for further clarification. I suggested some technical writing courses, but they got weird ideas from them, like writing documentation in a conversational style, which makes it somehow even worse...

alpinisme 3y ago
The key is not to focus on “what” needs documenting, but “how” someone will use your documentation: to get set up, to consume an api, to modify behavior, etc. If you write with the goal to help someone with X problem do Y to solve it, the empathy problem becomes a bit more tractable.
- mjw1007 3y ago
  I see this advice a lot, and I think it's making the problem worse. The most common form of bad documentation I come across is simply documentation with pieces missing: it uses terms without defining them, it tells you what problem an option is intended to solve but doesn't say what effect it actually has, and so on. One possible cause is the "empathy" theory: the author missed that bit out because they assumed the reader already knew it. But I think it's more common that the author just did a half-way job, because we don't have a documentation culture that takes being complete and correct as the minimum baseline. If that's the case, I think the advice authors need is to _not_ spend so much time thinking about what their reader is trying to do, and spend more time thinking "is what I've written complete?".
  - alpinisme 3y ago
    Sure. But they can’t know whether it’s complete without answering the question, “have I given the reader all the info they’d need to solve their problem?” Edit: grammar
  - zerojames 3y ago
    > it uses terms without defining them After reading this, I wrote a blog post. It will be part of the series, but probably released in a few days. I have so many ideas to cover! Now it's past midnight though, so I should probably get some sleep! Thank you for the ideas!
zerojames 3y ago
Having the engineer pair with someone who has never used the product before who also works in your org could help. I have a blog post coming up about this soon! I wrote documentation for a product earlier this year. A colleague with limited Python knowledge tried out the product using my documentation live, on a call. I learned so much from the process. We found bugs, we noticed that our documentation didn't have one clear usage path, which was confusing, and more. Watching someone work through your documentation was a bit uncomfortable, but it really helped me. I plan to do it again with another documentation project on my hands. Also, your colleague may need more direct feedback. I have picked up a lot of tips from the person who edits my work. Sometimes, I have an "aha" moment when I'm like "hm, this approach really is better!" and I take it with me in all that I write after that. > writing documentation in a conversational style The medium really matters. If the course was more about tutorials, a conversational style can be appropriate, if kept in check. If you are documenting open source software, it is different. Your colleague probably picked up good tips, but the course may not have shown how to use them properly.
- nullhole 3y ago
  > Having the engineer pair with someone who has never used the product before who also works in your org could help. I wholeheartedly agree with this. If you do this, especially with a user who is known for asking good questions, you will benefit greatly from it.
EricE 3y ago
Empathy for the curse of knowledge - it's why so much documentation is not great.
deleted 3y ago
[deleted]

alpinisme 3y ago

The key is not to focus on “what” needs documenting, but “how” someone will use your documentation: to get set up, to consume an api, to modify behavior, etc. If you write with the goal to help someone with X problem do Y to solve it, the empathy problem becomes a bit more tractable.

mjw1007 3y ago
I see this advice a lot, and I think it's making the problem worse. The most common form of bad documentation I come across is simply documentation with pieces missing: it uses terms without defining them, it tells you what problem an option is intended to solve but doesn't say what effect it actually has, and so on. One possible cause is the "empathy" theory: the author missed that bit out because they assumed the reader already knew it. But I think it's more common that the author just did a half-way job, because we don't have a documentation culture that takes being complete and correct as the minimum baseline. If that's the case, I think the advice authors need is to _not_ spend so much time thinking about what their reader is trying to do, and spend more time thinking "is what I've written complete?".
- alpinisme 3y ago
  Sure. But they can’t know whether it’s complete without answering the question, “have I given the reader all the info they’d need to solve their problem?” Edit: grammar
- zerojames 3y ago
  > it uses terms without defining them After reading this, I wrote a blog post. It will be part of the series, but probably released in a few days. I have so many ideas to cover! Now it's past midnight though, so I should probably get some sleep! Thank you for the ideas!

zerojames 3y ago

Having the engineer pair with someone who has never used the product before who also works in your org could help. I have a blog post coming up about this soon! I wrote documentation for a product earlier this year. A colleague with limited Python knowledge tried out the product using my documentation live, on a call. I learned so much from the process. We found bugs, we noticed that our documentation didn't have one clear usage path, which was confusing, and more. Watching someone work through your documentation was a bit uncomfortable, but it really helped me. I plan to do it again with another documentation project on my hands. Also, your colleague may need more direct feedback. I have picked up a lot of tips from the person who edits my work. Sometimes, I have an "aha" moment when I'm like "hm, this approach really is better!" and I take it with me in all that I write after that. > writing documentation in a conversational style The medium really matters. If the course was more about tutorials, a conversational style can be appropriate, if kept in check. If you are documenting open source software, it is different. Your colleague probably picked up good tips, but the course may not have shown how to use them properly.

nullhole 3y ago
> Having the engineer pair with someone who has never used the product before who also works in your org could help. I wholeheartedly agree with this. If you do this, especially with a user who is known for asking good questions, you will benefit greatly from it.

EricE 3y ago

Empathy for the curse of knowledge - it's why so much documentation is not great.

deleted 3y ago

[deleted]