I realized that the documentation I initially wrote correctly explained the problem and its solution, and that the comments in the source code were useful and sufficient.
Feels to me like you may have fallen into the same trap twice, of deeming documentation “sufficient” when it explains things to the satisfaction of the version of yourself that already understands the problem and the solution.
But by the time you achieve understanding, naturally the necessary insights (those required to cross the gap from a starting point of not understanding) feel obvious, unnecessary to mention, positively insulting to the future reader’s intelligence by their simplicity… and yet the you of a few hours earlier would have probably thanked yourself for spelling them out explicitly.
Without knowing all the specifics, it is of course impossible for me to say for sure if this actually applies to your case. But as a rule it seems like something to check for whenever you look back at documentation that has mysteriously come to seem more complete and sufficient without any actual edits.
“...But by the time you achieve understanding, naturally the necessary insights (those required to cross the gap from a starting point of not understanding) feel obvious, unnecessary to mention, positively insulting to the future reader’s intelligence by their simplicity...”
Incorrect appreciation. When I achieved understanding, the insights felt far from obvious up to the point it was necessary to include a warning. Take into account that that was only an illustrative example of the psychological effect of expecting an immediate understanding but instead finding something very hard to understand. Thanks for your point of view.
Feels to me like you may have fallen into the same trap twice, of deeming documentation “sufficient” when it explains things to the satisfaction of the version of yourself that already understands the problem and the solution.
But by the time you achieve understanding, naturally the necessary insights (those required to cross the gap from a starting point of not understanding) feel obvious, unnecessary to mention, positively insulting to the future reader’s intelligence by their simplicity… and yet the you of a few hours earlier would have probably thanked yourself for spelling them out explicitly.
Without knowing all the specifics, it is of course impossible for me to say for sure if this actually applies to your case. But as a rule it seems like something to check for whenever you look back at documentation that has mysteriously come to seem more complete and sufficient without any actual edits.
Incorrect appreciation. When I achieved understanding, the insights felt far from obvious up to the point it was necessary to include a warning.
Take into account that that was only an illustrative example of the psychological effect of expecting an immediate understanding but instead finding something very hard to understand.
Thanks for your point of view.