The problem with developers writing documentation is that they generally have too narrow of a view of things.
Here's an artificial example:
"Added a setting which allows you to change the size of a boba."
It doesn't answer any really useful questions, such as: why would you want to change the size of a boba? What is the effect of various sizes of boba? How does that interact with other settings?
As a database user, I actually want to know these things. Internally I have a mental model of how all these settings interact with the product, and I use information about the new setting to adjust that model.
For psql in particular, the documentation (as people have pointed out) shys away from anything too "opinionated."
But what it should do instead of have multiple opinionated examples. Multiple examples allow me to learn about the different tradeoffs and configuration options.
It reminds me of the old days, when the psql docs talked about optimization as a "black art", and basically said "it would be impossible to cover everything, so we won't cover anything."
Here's an artificial example:
"Added a setting which allows you to change the size of a boba."
It doesn't answer any really useful questions, such as: why would you want to change the size of a boba? What is the effect of various sizes of boba? How does that interact with other settings?
As a database user, I actually want to know these things. Internally I have a mental model of how all these settings interact with the product, and I use information about the new setting to adjust that model.
For psql in particular, the documentation (as people have pointed out) shys away from anything too "opinionated."
But what it should do instead of have multiple opinionated examples. Multiple examples allow me to learn about the different tradeoffs and configuration options.
It reminds me of the old days, when the psql docs talked about optimization as a "black art", and basically said "it would be impossible to cover everything, so we won't cover anything."