On Fri, 26 Mar 2021 at 06:15, Bruce Momjian <bruce@momjian.us> wrote:
On Thu, Mar 25, 2021 at 08:49:44AM -0400, David Steele wrote: > On 1/22/21 1:36 AM, Craig Ringer wrote: > > > > Would you mind attaching a revised version of the patch with your edits? > > Otherwise I'll go and merge them in once you've had your say on my > > comments inline below. > > Bharath, do the revisions in [1] look OK to you? > > > Bruce, Robert, can I have an opinion from you on how best to locate and > > structure these docs, or whether you think they're suitable for the main > > docs at all? See patch upthread. > > Bruce, Robert, any thoughts here?
I know I sent an email earlier this month saying we shouldn't over-document the backend hooks because the code could drift away from the README content:
Agreed. If you document the hooks too much, it allows them to drift away from matching the code, which makes the hook documentation actually worse than having no hook documentation at all.
However, for this doc patch, the content seem to be more strategic, so less likely to change, and hard to figure out from the code directly. Therefore, I think this would be a useful addition to the docs.
Thanks for the kind words. It's good to hear that it may be useful. Let me know if anything further is needed.
