The curse of knowledge is so real when it comes to writing documentation! I think it is the wrong approach to say "the only way out is to get someone else to read the thing and point out places that confuse them."
You state earlier in the article that we can't expect to rely on the fewer-numbered technical writers in the world to do all the great writing for us, and it's also true that we can't rely on asking for help from whoever is closest to give us helpful, actionable, relevant feedback on our writing.
It's crucial to consider the audience of what you're writing, as well as how representative someone is of that target audience when asking for feedback. Feedback can still be useful when it's given from someone that isn't the target audience of your piece, but it still needs to be evaluated in context (just like any data!) Bob Watson has a great blog post on how to evaluate feedback (documentation user research): https://docsbydesign.com/2022/04/04/tips-for-conducting-documentation-research-on-the-cheap/
I also wrote a few blog posts that can be helpful in this context:
I have a lot of opinions about documentation, and I'm really grateful that you're speaking up about the importance of good documentation, clear writing, and that writing well is a shared and valuable goal!
Documentation is hard. One of my issues with R is that package documentation often does not go very deep. I am currently struggling to find a path to create filled contour maps and overlay them on openstreet map basemaps - and it is super frustrating. Lots of online tutorials, but no one explains the data structures very well, or what the constraints are, or what the commands are really doing under the hood. So I'm having to pick that all apart with lots of failed attempts. Years ago I participated in the SciPy documentation effort (I got the T-shirt!), and it was a lot of work, but hopefully has helped people out since. I want to have a model in my head of what a command is doing. Then I can figure out how to use it. If I know that "everything in *nix is a pipe", then I can usually guess how something will work.
The curse of knowledge is so real when it comes to writing documentation! I think it is the wrong approach to say "the only way out is to get someone else to read the thing and point out places that confuse them."
You state earlier in the article that we can't expect to rely on the fewer-numbered technical writers in the world to do all the great writing for us, and it's also true that we can't rely on asking for help from whoever is closest to give us helpful, actionable, relevant feedback on our writing.
It's crucial to consider the audience of what you're writing, as well as how representative someone is of that target audience when asking for feedback. Feedback can still be useful when it's given from someone that isn't the target audience of your piece, but it still needs to be evaluated in context (just like any data!) Bob Watson has a great blog post on how to evaluate feedback (documentation user research): https://docsbydesign.com/2022/04/04/tips-for-conducting-documentation-research-on-the-cheap/
I also wrote a few blog posts that can be helpful in this context:
- for non-professional writers who want to get better at writing, read this: https://thisisimportant.net/2020/12/23/how-can-i-get-better-at-writing/
- for people who want to document a product from scratch, read this: https://thisisimportant.net/2021/09/21/from-nothing-to-something-with-minimum-viable-documentation/
- for people who want to rethink how they approach documentation and what it's for, read this: https://thisisimportant.net/2022/07/25/write-better-docs-with-a-product-thinking-mindset/
I have a lot of opinions about documentation, and I'm really grateful that you're speaking up about the importance of good documentation, clear writing, and that writing well is a shared and valuable goal!
Documentation is hard. One of my issues with R is that package documentation often does not go very deep. I am currently struggling to find a path to create filled contour maps and overlay them on openstreet map basemaps - and it is super frustrating. Lots of online tutorials, but no one explains the data structures very well, or what the constraints are, or what the commands are really doing under the hood. So I'm having to pick that all apart with lots of failed attempts. Years ago I participated in the SciPy documentation effort (I got the T-shirt!), and it was a lot of work, but hopefully has helped people out since. I want to have a model in my head of what a command is doing. Then I can figure out how to use it. If I know that "everything in *nix is a pipe", then I can usually guess how something will work.