5 ms·

> “ When you know something it is almost impossible to imagine what it is like not to know that thing. This is the curse of knowledge, and it is the root of cou

> “ When you know something it is almost impossible to imagine what it is like not to know that thing. This is the curse of knowledge, and it is the root of countless misunderstandings and inefficiencies.” A few months ago I came across an interesting actively developed project in embedded rust which was very technical. Full of acronyms and concepts that I was not familiar with. It took quite some time to get up to speed with how it all worked and so I took the time to add / expand README.md files for each example, explaining what the acronyms meant and the general gist of each example. It was a worthwhile exercise for myself and I figured that it was worth sharing the perspective of a beginner too. My benign pull request remains ignored and unmerged and it makes me feel like a bit of an imposter. I thought nothing of it at the time but now I wonder if this is classic case of “the curse of knowledge”. Perhaps the author just can’t see the value of it.

noisy_boy 6y ago
I think they are doing themselves a disservice by ignoring something that elevates overall understanding, ease of onboarding/troubleshooting and generally, the polish, of the project. I love documentation and usually manage to set aside time to add details in the README/wiki etc. It is a great way to share details with others and myself, six months down the line, because I don't have a super sharp memory.
- davidhyde 6y ago
  This is true but the “curse of knowledge” from the article explains why this can happen. It is easy for outsiders like you and me to see the value of such things but as an insider you can become blinded by your knowledge.
  - noisy_boy 6y ago
    That is possible. Though I equally like documenting things where I can be considered an "insider" that I know only other "insiders" will see. I think that it is about being able to see the usefulness, and beauty, of a well made documentation irrespective of the level of familiarity/proximity. Either you see value in it or you don't.
- kortilla 6y ago
  It depends. A README for a custom TCP implementation does not need a section explaining what TCP is, that’s just clutter. Some types of projects are targeting a specific user group that has to have some level of knowledge. Example: The readme for ripgrep does not explain what a shell is or how to pipe output.
metanonsense 6y ago
When new collegues are joining our team or people start working on a subsystem unfamiliar to them, I usually tell them that this is a great opportunity for us as an organization and that they should be very vocal about everything that appears strange. Their lack of knowledge is a valuable asset that must be exploited as long as it's fresh. Unfortunately, often it fades within a few days when their mental mode adapts to our quirks.
8iu9dua02 6y ago
You did nothing wrong. My team produces roughly equal amounts of documentation and finished product code or other artifacts for bank consulting engagements. Knowledge within the customer's organization is usually scattered all over the place and very few people know how it all fits together due to employee turnover and attrition. The actual customer (VP) is grateful when we are able to piece together what is really happening and the high level state of the system while we streamline their systems.
ncmncm 6y ago
Before you put a lot of work into something, it is a good idea to check if it is welcome. Nothing sucks up enthusiasm quite like blank rejection.
hutzlibu 6y ago
"Perhaps the author just can’t see the value of it. " Maybe so. But maybe he sees more the work of it. If the project is activly developed, means it is probably not stable. Documentation is only of value, if it is updated with the code. Worse than no documentation is only wrong documentation. So your explenation of the acronyms should remain true, but everything else maybe not. And it is work to figure out which is which and to verify, if a beginner comes and help with that. So now while it would be nice, if they would have written better documentation in the first place, or merged your PR, they probably think just too high of the cost.
angarg12 6y ago
This is actually the much less known flip side of the Dunning–Kruger effect [1]. > Moreover, competent students tended to underestimate their own competence, because they erroneously presumed that tasks easy for them to perform were also easy for other people to perform. [1] https://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect#Later_studies https://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect#...

noisy_boy 6y ago

I think they are doing themselves a disservice by ignoring something that elevates overall understanding, ease of onboarding/troubleshooting and generally, the polish, of the project. I love documentation and usually manage to set aside time to add details in the README/wiki etc. It is a great way to share details with others and myself, six months down the line, because I don't have a super sharp memory.

davidhyde 6y ago
This is true but the “curse of knowledge” from the article explains why this can happen. It is easy for outsiders like you and me to see the value of such things but as an insider you can become blinded by your knowledge.
- noisy_boy 6y ago
  That is possible. Though I equally like documenting things where I can be considered an "insider" that I know only other "insiders" will see. I think that it is about being able to see the usefulness, and beauty, of a well made documentation irrespective of the level of familiarity/proximity. Either you see value in it or you don't.
kortilla 6y ago
It depends. A README for a custom TCP implementation does not need a section explaining what TCP is, that’s just clutter. Some types of projects are targeting a specific user group that has to have some level of knowledge. Example: The readme for ripgrep does not explain what a shell is or how to pipe output.

metanonsense 6y ago

When new collegues are joining our team or people start working on a subsystem unfamiliar to them, I usually tell them that this is a great opportunity for us as an organization and that they should be very vocal about everything that appears strange. Their lack of knowledge is a valuable asset that must be exploited as long as it's fresh. Unfortunately, often it fades within a few days when their mental mode adapts to our quirks.

8iu9dua02 6y ago

You did nothing wrong. My team produces roughly equal amounts of documentation and finished product code or other artifacts for bank consulting engagements. Knowledge within the customer's organization is usually scattered all over the place and very few people know how it all fits together due to employee turnover and attrition. The actual customer (VP) is grateful when we are able to piece together what is really happening and the high level state of the system while we streamline their systems.

ncmncm 6y ago

Before you put a lot of work into something, it is a good idea to check if it is welcome. Nothing sucks up enthusiasm quite like blank rejection.

hutzlibu 6y ago

"Perhaps the author just can’t see the value of it. " Maybe so. But maybe he sees more the work of it. If the project is activly developed, means it is probably not stable. Documentation is only of value, if it is updated with the code. Worse than no documentation is only wrong documentation. So your explenation of the acronyms should remain true, but everything else maybe not. And it is work to figure out which is which and to verify, if a beginner comes and help with that. So now while it would be nice, if they would have written better documentation in the first place, or merged your PR, they probably think just too high of the cost.

angarg12 6y ago

This is actually the much less known flip side of the Dunning–Kruger effect [1]. > Moreover, competent students tended to underestimate their own competence, because they erroneously presumed that tasks easy for them to perform were also easy for other people to perform. [1] https://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect#Later_studies https://en.wikipedia.org/wiki/Dunning%E2%80%93Kruger_effect#...