Installation tutorial should be much more simple for newbies

From: Nikolay Samokhvalov <samokhvalov(at)gmail(dot)com>
To: PostgreSQL-documentation <pgsql-docs(at)postgresql(dot)org>
Subject: Installation tutorial should be much more simple for newbies
Date: 2014-04-06 09:17:37
Message-ID: CANNMO+KsxDNpBaP8QzvOM-UStba6Bp2MLbSR_WhTBpi+cvbe-Q@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

Hi there.

This is a question that I wanted to raise for a long time.

For years, from many people I've heard *many* times that PostgreSQL docs
are complicated for those who are just starting to use Postgres (or even
databases in general).

Recently, again, I had a couple of conversations with
possible-Postgres-users who had complaints about current Postgres docs.

We all love current docs for their good structure and clearness.

But if you a noob, they will really hurt you.

In this email I'll touch only one example – installation.

Let's check it:
http://www.postgresql.org/docs/9.3/interactive/tutorial-install.html

All one can briefly catch from this page is ..a link to Chapter
15. Installation from Source Code.

It's 2014 but we still thinking that the major way to install is
configure&&make&&make install, heh?
But that's exactly what current documentation is saying to new users:
> If you are installing PostgreSQL yourself, then refer to Chapter 15<http://www.postgresql.org/docs/9.3/interactive/installation.html> for
instructions on installation

Like no other options exist.

I am absolutely sure that newbie expects here something very simple. It
should be apt-get install or yum install, etc. But all he can quickly find
now in docs is frightening *short* version located at
http://www.postgresql.org/docs/9.3/interactive/install-short.html. Check it.

I SUGGEST:
1) to put very short lines of installation on most popular systems like
Debian/Ubuntu, RedHat/CentOS, FreeBSD or MacOS or Windows right into the
main tutorial page
2) to split the page "1.1. Installation" into two sections:
a. how to get PostgreSQL binaries and
b. how to install from source code,
mentioning that the first way is better for start (and it really is -- for
a new user), while the latter requires additional software (like gcc) to be
installed on the system.

I'm pretty sure that somebody with better English with me could write this
much better than me, but if no one has time for it at the moment I could do
it myself (expecting corrections afterwards).

This issue is very important to the project since PostgreSQL usage
continues to spread to wide range of users of various technical levels. It
is one of our "bottle necks" in new user acquisition process.

Browse pgsql-docs by date

  From Date Subject
Next Message Tom Lane 2014-04-08 20:41:06 Call for GIST/GIN/SP-GIST opclass documentation
Previous Message Amit Langote 2014-04-03 19:34:49 Re: Fwd: [GENERAL] Table Rewrite During ALTER TABLE ... ADD COLUMN ... DEFAULT NULL