On Sat, Jan 22, 2022 at 10:28 AM David G. Johnston
<david.g.johnston@gmail.com> wrote:
>
>
>
> On Saturday, January 22, 2022, James Coleman <jtc331@gmail.com> wrote:
>>
>> On Sat, Jan 22, 2022 at 12:35 AM David G. Johnston
>> <david.g.johnston@gmail.com> wrote:
>> >
>> > On Fri, Jan 21, 2022 at 5:14 PM James Coleman <jtc331@gmail.com> wrote:
>> >>
>> >>
>> >> > Really? That's horrid, because that's directly useful advice.
>> >>
>> >> Remedied, but rewritten a bit to better fit with the new style/goal of
>> >> that tip).
>> >>
>> >> Version 3 is attached.
>> >>
>> >
>> > Coming back to this after a respite I think the tip needs to be moved just like everything else. For much the
samereason (though this may only be a personal bias), I know what SQL Commands do the various things that DDL
encompasses(especially the basics like adding a column) and so the DDL section is really just a tutorial-like chapter
thatI will generally forget about because I will go straight to the official source which is the SQL Command Reference.
My future self would want the tip to show up there. If we put the tip after the existing paragraph that starts:
"Addinga column with a volatile DEFAULT or changing the type of an existing column..." the need to specify an example
functionin the tip goes away - though maybe it should be moved to the notes paragraph instead: "with a volatile DEFAULT
(e.g.,clock_timestamp()) or changing the type of an existing column..."
>>
>> In my mind that actually might be a reason to keep it that way. I
>> expect someone who's somewhat experienced to know there are things
>> (like table rewrites and scans) you need to consider and therefore go
>> to the ALTER TABLE page and read the details. But for someone newer
>> the tutorial page needs to introduce them to the idea that those
>> gotchas exist.
>>
>
> Readers of the DDL page are given a hint of the issues and directed to additional, arguably mandatory, reading. They
cannot worry about the nuances during their learning phase but instead can defer that reading until they actually have
needto alter a (large) table. But expecting them to read the command reference page is reasonable and is IMO the more
probableplace they will look when they start doing stuff in earnest. For the inexperienced reader breaking this up in
thismanner based upon depth of detail feels right to me.
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.
Thanks,
James Coleman
