Getting Started section
I just spent some time helping a former colleague work out some basic setup
issues after he got stuck trying to follow the Getting Started section of
the manual [1]http://www.postgresql.org/docs/9.4/static/tutorial-createdb.html and almost gave up. For what it's worth, he's very
technical, but does not deal with Postgres setup regularly.
The problems he ran into are fairly trivial, but I can see how he was
frustrated: the article makes very few assumptions about your environment
(which is great), but as a result is really vague and full of evasive
suggestions to "contact your administrator" if something is not working
(not great).
All I had to do (on Ubunutu) was run `sudo -u postgres createuser -s
$(whoami)`, and then omit the hostname (connecting to postgres:///maciek)
to use socket connections so I could take advantage of peer authentication
to avoid having to specify my password everywhere. The same thing worked
for him (on Debian, I believe).
Obviously this is not a solution for everyone, but I think packaging is
more common and more standardized these days, and administrators who may
have set up Postgres for you and can help you get started are less common.
I'm not sure how to address his frustrations, and balance that with
avoiding too many assumptions about users' environments, but it seems many
successful tools these days have explicit, platform-specific sections of
their setup to ensure that users can get started quickly and painlessly.
Could the Getting Started guide be improved here? Thoughts?
Thanks,
Maciek
[1]: http://www.postgresql.org/docs/9.4/static/tutorial-createdb.html
Maciek Sakrejda <m.sakrejda@gmail.com> writes:
I just spent some time helping a former colleague work out some basic setup
issues after he got stuck trying to follow the Getting Started section of
the manual [1] and almost gave up. For what it's worth, he's very
technical, but does not deal with Postgres setup regularly.
...
Obviously this is not a solution for everyone, but I think packaging is
more common and more standardized these days, and administrators who may
have set up Postgres for you and can help you get started are less common.
Agreed, but I should think that properly packaged versions of Postgres
will come with some package-specific instructions. Is that missing
in Debian's version, or out of date, or did he just not read it?
It might not be a bad thing for us to add some text near the head of
"Getting Started" pointing out that it's meant for manual installations,
and encouraging people to look to package-specific docs when present.
regards, tom lane
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
On Wed, Mar 2, 2016 at 9:36 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Maciek Sakrejda <m.sakrejda@gmail.com> writes:
I just spent some time helping a former colleague work out some basic
setup
issues after he got stuck trying to follow the Getting Started section of
the manual [1] and almost gave up. For what it's worth, he's very
technical, but does not deal with Postgres setup regularly.
...
Obviously this is not a solution for everyone, but I think packaging is
more common and more standardized these days, and administrators who may
have set up Postgres for you and can help you get started are lesscommon.
Agreed, but I should think that properly packaged versions of Postgres
will come with some package-specific instructions. Is that missing
in Debian's version, or out of date, or did he just not read it?
It's definitely there for debian - it's in
/usr/share/doc/postgresql-common/README.Debian.gz
It might not be a bad thing for us to add some text near the head of
"Getting Started" pointing out that it's meant for manual installations,
and encouraging people to look to package-specific docs when present.
And probably even exactly where those docs are to be found for at least the
most common platforms, I think.
The bigger question is, is it worth actually more or less importing the
contents of that into our main documentation. After all, 99% of our users
(or something thereabouts) are probably using the packaged versions, which
means that those parts of our documentation are simply irrelevant to
them... Which is not great when it's the "getting started" part.
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/
Magnus Hagander <magnus@hagander.net> writes:
On Wed, Mar 2, 2016 at 9:36 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Agreed, but I should think that properly packaged versions of Postgres
will come with some package-specific instructions. Is that missing
in Debian's version, or out of date, or did he just not read it?
It's definitely there for debian - it's in
/usr/share/doc/postgresql-common/README.Debian.gz
The bigger question is, is it worth actually more or less importing the
contents of that into our main documentation.
I'm definitely -1 on that; there are too many distinct packagings and they
change asynchronously to our releases. As a concrete example, the docs
for Red Hat's version needed to change when they moved from SysV init
scripts to systemd boot. Would we want to keep *both* versions of that
in our manual, and explain exactly which RHEL/CentOS/Fedora versions the
different texts applied to? No thanks ...
regards, tom lane
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
On Wed, Mar 2, 2016 at 7:51 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Magnus Hagander <magnus@hagander.net> writes:
On Wed, Mar 2, 2016 at 9:36 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Agreed, but I should think that properly packaged versions of Postgres
will come with some package-specific instructions. Is that missing
in Debian's version, or out of date, or did he just not read it?It's definitely there for debian - it's in
/usr/share/doc/postgresql-common/README.Debian.gzThe bigger question is, is it worth actually more or less importing the
contents of that into our main documentation.I'm definitely -1 on that; there are too many distinct packagings and they
change asynchronously to our releases. As a concrete example, the docs
for Red Hat's version needed to change when they moved from SysV init
scripts to systemd boot. Would we want to keep *both* versions of that
in our manual, and explain exactly which RHEL/CentOS/Fedora versions the
different texts applied to? No thanks ...
Would it be reasonable to just make it very clear the getting started
instructions are meant for install from source, and if you are using a
package, you should consult with your distribution?
--
Sent via pgsql-docs mailing list (pgsql-docs@postgresql.org)
To make changes to your subscription:
http://www.postgresql.org/mailpref/pgsql-docs
On Wed, Mar 2, 2016 at 3:51 PM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Magnus Hagander <magnus@hagander.net> writes:
On Wed, Mar 2, 2016 at 9:36 AM, Tom Lane <tgl@sss.pgh.pa.us> wrote:
Agreed, but I should think that properly packaged versions of Postgres
will come with some package-specific instructions. Is that missing
in Debian's version, or out of date, or did he just not read it?It's definitely there for debian - it's in
/usr/share/doc/postgresql-common/README.Debian.gzThe bigger question is, is it worth actually more or less importing the
contents of that into our main documentation.I'm definitely -1 on that; there are too many distinct packagings and they
change asynchronously to our releases. As a concrete example, the docs
for Red Hat's version needed to change when they moved from SysV init
scripts to systemd boot. Would we want to keep *both* versions of that
in our manual, and explain exactly which RHEL/CentOS/Fedora versions the
different texts applied to? No thanks ...
They have to be maintained *somewhere*. We could also ask the same people,
at least for the major platforms, to maintain it as part of our
documentation. Doing that would certainly make it easier for *new users*,
who are the target of this...
If not the whole docs, then we should at least include *exact* instructions
for where to find the platform specific docs for big platforms. As in
explicitly tell people where the doc files are located on debian, redhat,
etc.
--
Magnus Hagander
Me: http://www.hagander.net/
Work: http://www.redpill-linpro.com/