On Tue, Jan 25, 2022 at 8:49 AM James Coleman <jtc331@gmail.com> wrote: > Here's a version that looks like that. I'm not convinced it's an > improvement over the previous version: again, I expect more advanced > users to already understand this concept, and I think moving it to the > ALTER TABLE page could very well have the effect of burying i(amidst > the ton of detail on the ALTER TABLE page) concept that would be > useful to learn early on in a tutorial like the DDL page. But if > people really think this is an improvement, then I can acquiesce.
I vote for rejecting both of these patches.
0001 adds the following sentence to the documentation: "A <literal>NOT NULL</literal> constraint may be added to the new column in the same statement without requiring scanning the table to verify the constraint." My first reaction when I read this sentence was that it was warning the user about the absence of a hazard that no one would expect in the first place.
I agree. The wording that would make one even consider this has yet to have been introduced at this point in the documentation.
0002 moves some advice about adding columns with defaults from one part of the documentation to another. Maybe that's a good idea, and maybe it isn't, but it also rewords the advice, and in my opinion, the new wording is less clear and specific than the existing wording.
In the passing time I've had to directly reference the DDL chapter (which is a mix of reference material and tutorial) on numerous items so my desire to move the commentary away from here is less, but still I feel that the command reference page is the correct place for this kind of detail.
If we took away too much info and made things less clear let's address that. It can't be that much, we are talking about basically a paragraph of text here.
It also changes a sentence that mentions volatile defaults to give a specific example of a volatile function -- clock_timestamp -- probably because where the documentation was before that function was mentioned.However, that sentence seems clear enough as it is and does
not really need an example.
Nope, the usage and context in the patch is basically the same as the existing usage and context.
