Installation instructions vs binaries

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
10 messages Options
Reply | Threaded
Open this post in threaded view
|

Installation instructions vs binaries

Magnus Hagander-2
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.

--

docs_binary_installs.patch (6K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Installation instructions vs binaries

David G Johnston
On Wed, Jul 15, 2020 at 4:13 AM Magnus Hagander <[hidden email]> 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.

Reply | Threaded
Open this post in threaded view
|

Re: Installation instructions vs binaries

Magnus Hagander-2


On Thu, Jul 16, 2020 at 6:25 PM David G. Johnston <[hidden email]> wrote:
On Wed, Jul 15, 2020 at 4:13 AM Magnus Hagander <[hidden email]> 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?

--

docs-binary-installs-v2.patch (6K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Installation instructions vs binaries

Tom Lane-2
Magnus Hagander <[hidden email]> writes:
> Yeah, that makes a lot of sense. How about like this?

Isn't this pretty duplicative of d2511d713?

                        regards, tom lane


Reply | Threaded
Open this post in threaded view
|

Re: Installation instructions vs binaries

Magnus Hagander-2

On Tue, Sep 8, 2020 at 4:06 PM Tom Lane <[hidden email]> wrote:
Magnus Hagander <[hidden email]> 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?

--
Reply | Threaded
Open this post in threaded view
|

Re: Installation instructions vs binaries

Tom Lane-2
Magnus Hagander <[hidden email]> 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


Reply | Threaded
Open this post in threaded view
|

Re: Installation instructions vs binaries

Magnus Hagander-2


On Tue, Sep 8, 2020 at 4:27 PM Tom Lane <[hidden email]> wrote:
Magnus Hagander <[hidden email]> 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

Reply | Threaded
Open this post in threaded view
|

Re: Installation instructions vs binaries

Tom Lane-2
Magnus Hagander <[hidden email]> 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


Reply | Threaded
Open this post in threaded view
|

Re: Installation instructions vs binaries

Magnus Hagander-2
On Tue, Sep 8, 2020 at 4:51 PM Tom Lane <[hidden email]> wrote:
Magnus Hagander <[hidden email]> 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? 

--

docs-binary-installs-v3.patch (4K) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Installation instructions vs binaries

David G Johnston
On Tue, Sep 8, 2020 at 8:05 AM Magnus Hagander <[hidden email]> wrote:
On Tue, Sep 8, 2020 at 4:51 PM Tom Lane <[hidden email]> wrote:
Magnus Hagander <[hidden email]> 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.