Received: from malur.postgresql.org ([217.196.149.56]) by arkaria.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1uhcsI-0023kw-QT for pgsql-docs@arkaria.postgresql.org; Thu, 31 Jul 2025 23:39:51 +0000 Received: from localhost ([127.0.0.1] helo=malur.postgresql.org) by malur.postgresql.org with esmtp (Exim 4.94.2) (envelope-from ) id 1uhcsH-004Eul-Ke for pgsql-docs@arkaria.postgresql.org; Thu, 31 Jul 2025 23:39:49 +0000 Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29]) by malur.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 (Exim 4.94.2) (envelope-from ) id 1uhcsH-004Eud-CQ for pgsql-docs@lists.postgresql.org; Thu, 31 Jul 2025 23:39:49 +0000 Received: from mail-oo1-xc36.google.com ([2607:f8b0:4864:20::c36]) by magus.postgresql.org with esmtps (TLS1.3) tls TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 (Exim 4.96) (envelope-from ) id 1uhcsE-0006Tt-1o for pgsql-docs@lists.postgresql.org; Thu, 31 Jul 2025 23:39:48 +0000 Received: by mail-oo1-xc36.google.com with SMTP id 006d021491bc7-615917848ccso128112eaf.3 for ; Thu, 31 Jul 2025 16:39:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1754005184; x=1754609984; darn=lists.postgresql.org; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:from:to:cc:subject:date:message-id:reply-to; bh=+HvtLGXj9IKnhCpWa67B9MUdBLV6XASe6a2dEvX5n9A=; b=BUjbEn/u5PI0BGWB41m3Aajo1ZCt/2nAHPHiO0upxjCi2Mezv63kRQKlqjrnXgX/t9 7yBBFgA76lPOcwumrFNoyxPxvn6JozqqpGNcjJltOkS6QNnUqhgtG8lwT+drH/HVYXXT wXh2b+yJD6fO4gX/vZZ32RaYlaZYG6mP0Xh9/ETRxgmQgMDUO4m3UbhbQp72Awn6t83Q AHVN4NkbyJnwZjmAGsWWx3wHWBpRjzEcTI35tQyZ+TgT8qwUOM1v4ZVz1QQiEWKYlbpL 5GJVr1oUsO/ncZ6HvdyplJweQesZEJwOxchtSMwDLZjRikbGGIa8EMojflwNv4df9Qii QzzA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1754005184; x=1754609984; h=cc:to:subject:message-id:date:from:in-reply-to:references :mime-version:x-gm-message-state:from:to:cc:subject:date:message-id :reply-to; bh=+HvtLGXj9IKnhCpWa67B9MUdBLV6XASe6a2dEvX5n9A=; b=XANlXeGg8RBV+09j//AqB6sF/1ET0aXf6Zr6fZlZBsp5ZzTuvKtqemR/kQOwVvK4Zd lyM8S2auTik1JnOjFUQUxCTTORJBZLxCFu1/MJOvqbgYOHoucoUvfyjfsb0I+sPEHVGx sGL8Vhe9JpyEssnA0Yb8ZxBFJ7AGZgRtU6vPTIvBzsHPipanVaPwRkpeyh4XeUVKZ18C E86IllliDw4rk8LNXvKPbGDc2Bz6+S1sitBURlFwMzIoCmnvWRC2dk76BoHhQAnrU2Wc oDnime85Y8OmtR4wgemF9Q56VuM6b6idesYCzwD//70uIXmqKejOto4yz58R65X2LO6r 7JeQ== X-Forwarded-Encrypted: i=1; AJvYcCVYP9rTFutkIaza2pm9SedIw1Dz4lA/BdO2ssj3ODiPlgI1K/MVjUoeZIsEr34bYcOaRhH8A7zeE5g+@lists.postgresql.org X-Gm-Message-State: AOJu0YyRryHCajncRjjAdOSwGN7gFkV0IgLRmv8HcmFsSxGeoYsxv+pr Dztlv3urIMp8sfDu2NRGRp2pRcg9pg+vEv3CwSAZd8NlkhBY4yjhk79PBzR9lFSBXlKQPwPSw7q M/6CXDClOzkztSYMaIKVkcTo/zki/ojA9rbxW X-Gm-Gg: ASbGncuzZkfMx5Mh7KFjoT6fMyZHgXI0gKlTKMzQ4NrOFJBMDee0A68PjXFGQ4gEWSL jfdiLeemY79GK6E21R8B9T+bKN0oL0Bng3TruCjRmkKlWTRT+UlwZp+S0+A/zcOpaH6lpfcMc4E Xj2MwpYb9d4A6sAPokng7/iU9VHo3f7gMXCh2TcBSMg5i4/zYwkPGfy5K6Fwy/Xb1wcVs09VL/j mkE/Cqs73hUMN5q7DnGsxd1A8qPoVUUKOkEqrGsL3jS0frghvw= X-Google-Smtp-Source: AGHT+IEVWRnbdH26h44OLMmTZNnXVnLJIDYuwl+OMlVSiEhXmkWIUC344Mz/VQFyRz0+qpWFZWhr8aawJdPDWw4tPSQ= X-Received: by 2002:a05:6820:4cc2:b0:615:9107:fae3 with SMTP id 006d021491bc7-6195d30c746mr5403354eaf.8.1754005184489; Thu, 31 Jul 2025 16:39:44 -0700 (PDT) MIME-Version: 1.0 References: In-Reply-To: From: "David G. Johnston" Date: Thu, 31 Jul 2025 16:39:08 -0700 X-Gm-Features: Ac12FXwtmMA0N2vzlaoCJivPN0tubgc5zNgce8zHdwOY-0NX_xy4DVfvfPeUsbM Message-ID: Subject: Re: Lets prohibit predicting the future in the documentation. To: Peter Smith Cc: Magnus Hagander , David Rowley , PostgreSQL Documentation Content-Type: multipart/alternative; boundary="000000000000f4ae24063b422732" List-Id: List-Help: List-Subscribe: List-Post: List-Owner: List-Archive: Archived-At: Precedence: bulk --000000000000f4ae24063b422732 Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable On Thu, Jul 31, 2025 at 4:24=E2=80=AFPM Peter Smith = wrote: > On Thu, Jul 31, 2025 at 8:05=E2=80=AFPM Magnus Hagander > wrote: > > > > > > > > On Thu, Jul 31, 2025 at 5:03=E2=80=AFAM David Rowley > wrote: > >> > >> On Thu, 31 Jul 2025 at 14:17, David G. Johnston > >> wrote: > >> > > >> > Came across this again today...we added, way back in v11: > >> > > >> > "This limitation will likely be removed in a future version of > PostgreSQL." > >> > > >> > https://www.postgresql.org/docs/18/sql-createstatistics.html > >> > >> This sort of thing doesn't particularly upset me. I don't believe we > >> should hide the fact that certain features might need more work. If it > >> inspires someone to work on making improvements, wouldn't it be > >> worthwhile keeping these? A huge amount of stuff gets done around here > >> because people find some inspiration to make things better. I don't > >> believe all those people need to experience the problems first-hand to > >> be able to fix them. Plenty of people arrive here just looking to get > >> involved and make a difference. I presume that something like this > >> being mentioned in the docs likely has a much better "we actually want > >> this feature" ratio than the TODO list does. I also imagine it's more > >> likely to inspire users of PostgreSQL to get involved in developing > >> than the TODO list is. > >> > >> -1 from me. > > > > > > I can agree that the "will likely be removed" is a bad wording, and > clearly it was wrong :) But something like "could be removed" would conv= ey > the important message that it is not a limitation of the concept itself, > it's just something that hasn't been done yet -- and would perhaps > encourage exactly the sort of thing yuo'r suggesting. Where as "will like= ly > be removed" almost sounds like someone is already working on it. > > > > FYI, there are quite a lot like this. Mostly the docs are worded using > "may/might/can" rather than "will" be changed. > > Yeah, I haven't been able to dig into the source yet on this topic but basically that says to me that lots of people, with good intentions, want to couch bad news (limitations) with something positive (hope). But in the documentation it ends up almost inevitably turning into false hope. There is no good way to extract all these "TODO" items from the HTML docs and seems like a non-optimal method for transferring knowledge to potential developers who may choose to try and remove such limitations. David J. --000000000000f4ae24063b422732 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
On Thu, Jul 31, 2025 at 4:24=E2=80=AFPM Peter Smith <smithpb2250@gmail.com> wrote:=
On Thu, Jul 31, 2025 at 8:05=E2= =80=AFPM Magnus Hagander <magnus@hagander.net> wrote:
>
>
>
> On Thu, Jul 31, 2025 at 5:03=E2=80=AFAM David Rowley <dgrowleyml@gmail.com> w= rote:
>>
>> On Thu, 31 Jul 2025 at 14:17, David G. Johnston
>> <david.g.johnston@gmail.com> wrote:
>> >
>> > Came across this again today...we added, way back in v11:
>> >
>> > "This limitation will likely be removed in a future vers= ion of <productname>PostgreSQL</productname>."
>> >
>> > https://www.postgresql.org= /docs/18/sql-createstatistics.html
>>
>> This sort of thing doesn't particularly upset me. I don't = believe we
>> should hide the fact that certain features might need more work. I= f it
>> inspires someone to work on making improvements, wouldn't it b= e
>> worthwhile keeping these? A huge amount of stuff gets done around = here
>> because people find some inspiration to make things better. I don&= #39;t
>> believe all those people need to experience the problems first-han= d to
>> be able to fix them. Plenty of people arrive here just looking to = get
>> involved and make a difference. I presume that something like this=
>> being mentioned in the docs likely has a much better "we actu= ally want
>> this feature" ratio than the TODO list does. I also imagine i= t's more
>> likely to inspire users of PostgreSQL to get involved in developin= g
>> than the TODO list is.
>>
>> -1 from me.
>
>
> I can agree that the "will likely be removed" is a bad wordi= ng, and clearly it was wrong :) But=C2=A0 something like "could be rem= oved" would convey the important message that it is not a limitation o= f the concept itself, it's just something that hasn't been done yet= -- and would perhaps encourage exactly the sort of thing yuo'r suggest= ing. Where as "will likely be removed" almost sounds like someone= is already working on it.
>

FYI, there are quite a lot like this. Mostly the docs are worded using
"may/might/can" rather than "will" be changed.


Yeah, I haven't been able to dig int= o the source yet on this topic but basically that says to me that lots of p= eople, with good intentions, want to couch bad news (limitations) with some= thing positive (hope).=C2=A0 But in the documentation it ends up almost ine= vitably=C2=A0turning into false hope.

There is no good= way to extract all these "TODO" items from the HTML docs and see= ms like a non-optimal method for transferring knowledge to potential develo= pers who may choose to try and remove such limitations.

<= div class=3D"gmail_default" style=3D"font-family:arial,helvetica,sans-serif= ">David J.

--000000000000f4ae24063b422732--