(devblogs.microsoft.com)
Another example of why technical writing is difficult, I think.
I always liked that mindset, and it helped teach me the important lesson that sometimes being the person who asks very basic questions because I don't understand things can make me valuable to the teams I work on. There are certainly times when the answer makes me go "oh, duh!", and I feel a little sheepish, but the feeling doesn't last very long, and no one has ever held it against me, whereas the times when it leads somewhere interesting and potentially to better documentation for people coming after me are far more frequent and memorable to everyone involved.
This isn't to say that the burden should fall on the ones who are reading the documentation rather than writing it, but to encourage people who are in the position of being frustrated and confused to take advantage of those moments, because they can make you very valuable to your team in addition to helping you learn. If you're on a team that operates in good faith, the burden for documenting things well can be shared, and in the long run it will matter less who's job it is to keep it updated and more about whether everyone is contributing however they can to maintain the quality (and if you're on a team that operates in bad faith, you have my permission to keep quiet and do whatever you can to get through that experience, not that you need it from me!)
For anyone not familiar with the term, Chesterton's Fence is the idea that you should understand why a rule exists before trying to remove it or work around it: https://fs.blog/chestertons-fence/
Here the issue is not that the rule was removed, but that the code followed the wording while missing the reason the rule existed.
1. I want to remove a rule
2. Understand why that rule is in place before proceeding
This article deals with the second part, but not the first. So it is only about about half of Chesterton's fence at best.
In these examples, a rule (avoid blocking calls) is in place to guide the programmer to a performant system. Programmers apparently thought that if they found a way to avoid directly blocking calls, but managed to indirectly block, they had still obeyed the rule. And strictly by the most narrow reading of the rule they had obeyed it. But they had defeated the purpose of the rule.
So definitely Chesterton's Fence adjacent, but not Chesterton's Fence itself.
First day, a monkey climbs the scale, gets the banana and is happy.
Second day, they start spraying whomever gets on the scale. Monkeys hate this. They learn not to climb.
Third day, they take a monkey out and replace with another. The new monkey sees a banana up there and tries climbing the scale. He literally gets beaten out by the others, like "seems like you're new here".
Days 4-12, they've replaced one monkey per day, so that no monkey was here when it was possible to get the banana. None of them have ever been sprayed either. Still, they enforce the rule not to climb up there.
I am putting this example because in our society as well, there are many rules that are enforced without anyone questioning the "why". Yet the "why" is often more important to know than the rule itself.
Designers know this dichotomy between the "why" and the "how". Most people don't.
The lessons I'd take away from the experiment would be 1) be sure to tell people why the rules exist, but also 2) follow the rules even if there's no apparent reason for them, otherwise you might get smacked down by some unimaginably powerful entity you're barely even aware of.
> The documentation should open with something like this:
>> The callback function must perform its work quickly without blocking. If you need to do complex work or synchronize with other threads or processes, do the work asynchronously, such as by using System Worker Threads.
A change was made, but not the change that Raymond thinks would explain why the list is there anyway.