Installation instructions vs binaries

On Wed, Jul 15, 2020 at 4:13 AM Magnus Hagander <magnus@hagander.net> wrote:

It's kind of strange that if you start your PostgreSQL journey by reading
our instructions, you get nothing useful about installing PostgreSQL from
binary packages other than "go ask somebody else about it". Yet we have
pretty good step by step instructions on our *website* for it.

Attached patch adds a chapter to the docs about installing from binaries,
and refers those users to the website download instructions (and updates
the Windows instructions to include an actual link to the website).

It also adds mention of it in a few other places - -there are probably
more that could use some help with that in the future. But I've seen a lot
of people get confused by our documentation assuming everything is from
source when it comes to initdb and pg_ctl that I think it's worth specially
mentioning it there.

Thanks. Adding tips calling out common package-specific/handled pieces
seems ok.

One typo for the patch as-is:

+   When PostgreSQL is installed using binary packages, starting and
stopping
+    of the system is normally integrated with the service management on the
+    platform. Refer to the documentation for the documentation for these
+    packages and the platform for more information.

Remove "for the documentation"

However, maybe we should avoid repeated use of the passive "When PostgreSQL
is installed using binary packages". Consider just: "PostgreSQL binary
packages". e.g.,

PostgreSQL binary packages normally include platform-appropriate service
management (starting and stopping). Consult the package documentation for
more information.

(the other two can be rewording similarly if this is deemed better - all
three should be consistent).

David J.

On Thu, Jul 16, 2020 at 6:25 PM David G. Johnston <
david.g.johnston@gmail.com> wrote:

On Wed, Jul 15, 2020 at 4:13 AM Magnus Hagander <magnus@hagander.net>
wrote:

It's kind of strange that if you start your PostgreSQL journey by reading
our instructions, you get nothing useful about installing PostgreSQL from
binary packages other than "go ask somebody else about it". Yet we have
pretty good step by step instructions on our *website* for it.

Attached patch adds a chapter to the docs about installing from binaries,
and refers those users to the website download instructions (and updates
the Windows instructions to include an actual link to the website).

It also adds mention of it in a few other places - -there are probably
more that could use some help with that in the future. But I've seen a lot
of people get confused by our documentation assuming everything is from
source when it comes to initdb and pg_ctl that I think it's worth specially
mentioning it there.

Dang, I forgot to add this to the cf page, so I forgot about it myself :)

Thanks. Adding tips calling out common package-specific/handled pieces

seems ok.

One typo for the patch as-is:

+   When PostgreSQL is installed using binary packages, starting and
stopping
+    of the system is normally integrated with the service management on
the
+    platform. Refer to the documentation for the documentation for these
+    packages and the platform for more information.

Remove "for the documentation"

Hah, yeah, that's cute.

However, maybe we should avoid repeated use of the passive "When PostgreSQL

is installed using binary packages". Consider just: "PostgreSQL binary
packages". e.g.,

PostgreSQL binary packages normally include platform-appropriate service
management (starting and stopping). Consult the package documentation for
more information.

(the other two can be rewording similarly if this is deemed better - all
three should be consistent).

Yeah, that makes a lot of sense. How about like this?

--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/&gt;
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/&gt;

Magnus Hagander <magnus@hagander.net> writes:

Yeah, that makes a lot of sense. How about like this?

Isn't this pretty duplicative of d2511d713?

regards, tom lane

On Tue, Sep 8, 2020 at 4:06 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

Magnus Hagander <magnus@hagander.net> writes:

Yeah, that makes a lot of sense. How about like this?

Isn't this pretty duplicative of d2511d713?

Eh yes, I clearly missed that one -- that's what I get for forgetting to
put it in the CF :)

That said, I still think it's worthwhile to have a separate chapter on
installing from binaries, ahead of the source one, rather than just a note
in the source chapter -- and with proper links to the website.

And I think Davids comment about repetitive language would apply to yours
as well, and should maybe be simplified there too?

--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/&gt;
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/&gt;

Magnus Hagander <magnus@hagander.net> writes:

And I think Davids comment about repetitive language would apply to yours
as well, and should maybe be simplified there too?

Per the discussion in the other thread, we concluded that being repetitive
was the only way to be sure people would see the material at all.
If you look at

https://www.postgresql.org/docs/devel/runtime.html

a lot of people are going to follow one of the section links before
they ever see any of the chapter head material.

(This would be less of a problem if we could get DocBook to insert
the chapter TOC at the bottom of the page not the top. I dunno
how to do that, though.)

regards, tom lane

On Tue, Sep 8, 2020 at 4:27 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

Magnus Hagander <magnus@hagander.net> writes:

And I think Davids comment about repetitive language would apply to yours
as well, and should maybe be simplified there too?

Per the discussion in the other thread, we concluded that being repetitive
was the only way to be sure people would see the material at all.
If you look at

https://www.postgresql.org/docs/devel/runtime.html

a lot of people are going to follow one of the section links before
they ever see any of the chapter head material.

I think we're talking about a different repetitiveness. If I apply Davids
suggestion to that patch, then instead of:

+  <para>
+   If you are using a pre-packaged version
+   of <productname>PostgreSQL</productname>, it may well have a specific
+   convention for where to place the data directory, and it may also
+   provide a script for creating the data directory.  In that case you

It would say something like
Pre-packaged versions of PostgreSQL may have a specific convention....

(rest unchanged).

//Magnus

Magnus Hagander <magnus@hagander.net> writes:

I think we're talking about a different repetitiveness. If I apply Davids
suggestion to that patch, then instead of:

+  <para>
+   If you are using a pre-packaged version
+   of <productname>PostgreSQL</productname>, it may well have a specific
+   convention for where to place the data directory, and it may also
+   provide a script for creating the data directory.  In that case you

It would say something like
Pre-packaged versions of PostgreSQL may have a specific convention....
(rest unchanged).

[ shrug... ] Well, I wrote that text, so naturally I like it the way
it is ;-). Perhaps a neutral observer would like the shorter version
better, not sure. But I think pluralizing "versions" is going to make
it harder to construct the rest of the sentence non-ambiguously.
You really only want to be talking about one data directory location
and one wrapper script.

regards, tom lane

On Tue, Sep 8, 2020 at 4:51 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

Magnus Hagander <magnus@hagander.net> writes:

I think we're talking about a different repetitiveness. If I apply Davids
suggestion to that patch, then instead of:

+  <para>
+   If you are using a pre-packaged version
+   of <productname>PostgreSQL</productname>, it may well have a specific
+   convention for where to place the data directory, and it may also
+   provide a script for creating the data directory.  In that case you

It would say something like
Pre-packaged versions of PostgreSQL may have a specific convention....
(rest unchanged).

[ shrug... ] Well, I wrote that text, so naturally I like it the way
it is ;-). Perhaps a neutral observer would like the shorter version
better, not sure. But I think pluralizing "versions" is going to make
it harder to construct the rest of the sentence non-ambiguously.
You really only want to be talking about one data directory location
and one wrapper script.

Yeah, I guess it can work either way. I don't feel too strongly about that
one, so I'll leave it to David to argue for that standpoint if he thinks it
applies here as well.

That leaves just the part of adding the actual new chapter of my patch.
PFA. Thoughts on that?

--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/&gt;
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/&gt;

On Tue, Sep 8, 2020 at 8:05 AM Magnus Hagander <magnus@hagander.net> wrote:

On Tue, Sep 8, 2020 at 4:51 PM Tom Lane <tgl@sss.pgh.pa.us> wrote:

Magnus Hagander <magnus@hagander.net> writes:

I think we're talking about a different repetitiveness. If I apply

Davids

suggestion to that patch, then instead of:

+  <para>
+   If you are using a pre-packaged version
+   of <productname>PostgreSQL</productname>, it may well have a

specific

+   convention for where to place the data directory, and it may also
+   provide a script for creating the data directory.  In that case you

It would say something like
Pre-packaged versions of PostgreSQL may have a specific convention....
(rest unchanged).

[ shrug... ] Well, I wrote that text, so naturally I like it the way
it is ;-). Perhaps a neutral observer would like the shorter version
better, not sure. But I think pluralizing "versions" is going to make
it harder to construct the rest of the sentence non-ambiguously.
You really only want to be talking about one data directory location
and one wrapper script.

Yeah, I guess it can work either way. I don't feel too strongly about that
one, so I'll leave it to David to argue for that standpoint if he thinks it
applies here as well.

The shorter version I suggest does require some implicit understanding on
the part of the reader - that while I speak of the collective each
individual member can vary. The current version just speaks relative to
some already chosen member. Given the target audience my only concern with
the more wordy version would be impaired comprehension but that doesn't
seem likely, so I would maintain status quo.

That leaves just the part of adding the actual new chapter of my patch.

PFA. Thoughts on that?

I think that it is a good idea - and the patch reads well. I kinda want to
be blunt, though, and point out that if the user is using a pre-packaged
version that the packager, and not the core team, accepts responsibility
for problem reports related to installation, on their support channel.
Please don't use pg-bugs. We provide links on our website as a convenience,
not as endorsement.

David J.

On 15 Sep 2020, at 02:43, David G. Johnston <david.g.johnston@gmail.com> wrote:
On Tue, Sep 8, 2020 at 8:05 AM Magnus Hagander <magnus@hagander.net <mailto:magnus@hagander.net>> wrote:

That leaves just the part of adding the actual new chapter of my patch. PFA. Thoughts on that?

+1 on this version of the patch.

It seems a bit odd to me to capitalize Download, but since it's the name of the
referenced section I guess it's ok. Personally I'd have lowercased it.
+ the Download section on the <productname>PostgreSQL</productname> website at

I kinda want to be blunt, though, and point out that if the user is using a pre-packaged version that the packager, and not the core team, accepts responsibility for problem reports related to installation, on their support channel. Please don't use pg-bugs.

I don't think it's reasonable to expect users to be able to separate bugs
caused by the installer and supporting scripts/wrappers, and those by for
example initdb. AFAICR it's mostly the Windows installer which we get reports
for on -bugs, and the devs responsible for said installer have been quite quick
at responding so I don't really see a problem.

We provide links on our website as a convenience, not as endorsement.

Do we? For the software catalogue we explicitly say that we don't endorse any
software linked to but we don't do that anywhere on the PostgreSQL downloads
section. Since these links are very much curated, I would think it reasonable
for users to think of them as endorsed by PGDG.

cheers ./daniel

On Tue, Oct 6, 2020 at 1:58 PM Daniel Gustafsson <daniel@yesql.se> wrote:

On 15 Sep 2020, at 02:43, David G. Johnston <david.g.johnston@gmail.com>

wrote:

On Tue, Sep 8, 2020 at 8:05 AM Magnus Hagander <magnus@hagander.net

<mailto:magnus@hagander.net>> wrote:

That leaves just the part of adding the actual new chapter of my patch.

PFA. Thoughts on that?

+1 on this version of the patch.

It seems a bit odd to me to capitalize Download, but since it's the name
of the
referenced section I guess it's ok. Personally I'd have lowercased it.
+ the Download section on the <productname>PostgreSQL</productname>
website at

Yeah, that was based on the fact that it's like that on the website. But I
agree, it's a bit weird. I'll go change it.

Thanks to you both, pushed!

I kinda want to be blunt, though, and point out that if the user is

using a pre-packaged version that the packager, and not the core team,
accepts responsibility for problem reports related to installation, on
their support channel. Please don't use pg-bugs.

I don't think it's reasonable to expect users to be able to separate bugs
caused by the installer and supporting scripts/wrappers, and those by for
example initdb. AFAICR it's mostly the Windows installer which we get
reports
for on -bugs, and the devs responsible for said installer have been quite
quick
at responding so I don't really see a problem.

In some cases they probably can, but not in all cases. We do have people
reporting debian isssues directly to debian and redhat issues directly to
either redhat or our rpm packagers. Just not always.

We need a better workflow for reporting that, but this should really be
coded into the website (I have a draft patch somewhere that I never
finished), and not in the documentation. Because just saying "go somewhere
else" doesn't help anybody, unless we can also tell them where this
"somewhere else" is.

We provide links on our website as a convenience, not as endorsement.

Do we? For the software catalogue we explicitly say that we don't endorse
any
software linked to but we don't do that anywhere on the PostgreSQL
downloads
section. Since these links are very much curated, I would think it
reasonable
for users to think of them as endorsed by PGDG.

The things we have listed in the main download section on our website is
definitely being endorsed by the project. And as you say, the product
catalogue is different.

--
Magnus Hagander
Me: https://www.hagander.net/ <http://www.hagander.net/&gt;
Work: https://www.redpill-linpro.com/ <http://www.redpill-linpro.com/&gt;

Magnus,

[offline]

Does this resolve the 2020-11 commitfest entry?

https://commitfest.postgresql.org/30/2726/

David J.

On Tue, Oct 6, 2020 at 5:21 AM Magnus Hagander <magnus@hagander.net> wrote:

Sorry, not offline but not a big deal...

On Wed, Oct 21, 2020 at 8:40 AM David G. Johnston <
david.g.johnston@gmail.com> wrote:

Ah, yes it does. Thanks -- will close.

//Magnus

On Wed, Oct 21, 2020 at 5:40 PM David G. Johnston <
david.g.johnston@gmail.com> wrote: