Обсуждение: Installation instructions vs binaries
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.
Вложения
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 <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 <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
+ 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?
Вложения
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, andnot the core team, accepts responsibility for problem reports related to installation, on their support channel. Pleasedon'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,
[offline]
Does this resolve the 2020-11 commitfest entry?
David J.
On Tue, Oct 6, 2020 at 5:21 AM Magnus Hagander <magnus@hagander.net> wrote:
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 atYeah, 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!
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:
Magnus,[offline]
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:
Magnus,[offline]Does this resolve the 2020-11 commitfest entry?David J.On Tue, Oct 6, 2020 at 5:21 AM Magnus Hagander <magnus@hagander.net> wrote: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 atYeah, 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!