Tutorial section of documentation: enhancements needed

From: Lætitia Avrot <laetitia(dot)avrot(at)gmail(dot)com>
To: pgsql-docs(at)postgresql(dot)org
Subject: Tutorial section of documentation: enhancements needed
Date: 2019-02-12 08:06:21
Message-ID: CAB_COdjnQtDcg454fZxSM0u--VvJdTuD2heBsXCskQRpAo=abw@mail.gmail.com
Views: Raw Message | Whole Thread | Download mbox | Resend email
Thread:
Lists: pgsql-docs

Hi all,

While being a Google Code-In Mentor, I had a nice chat with Tanvir13559 and
Nathan1337 about [Postgres' tutorial](
https://www.postgresql.org/docs/current/tutorial.html) and they came up
with two constructive comments:

- That doc doesn't help anyone willing to install postgres on their laptop
(the installation part refers to [chapter 16](
https://www.postgresql.org/docs/current/installation.html) which is
"installation from source code", not the easiest way for a beginner to
install Postgres).
- Most of them were under MS Windows and everything in the doc is Linux
related (it's not that true, but that's their impression)

What I would add is that, unlike nowadays tutorials, that tutorial will
focus on explaining how it works instead of giving a recipe of how to
install, how to configure basically, how to connect. I think that behind
the word "tutorial", millennials don't have the same concepts than more
older ones(me included), so that there are misunderstandings and I think
that's no good.

Now, what can we do ?

To me, there are 2 options:
- either, we change the "Tutorial" name of that chapter, so millenials
don't think they will find a step by step doc on how to install, configure
and connect to Postgres and add a tutorial page (the name can be changed)
on the postgresql.org website
- either we change the first part "getting started" to add practical
installation steps (but it might be redundant with the download page of
postgresql.org), basic configuration (if needed, as how to open connection
for your OS user, that kind of things) and how to connect with psql on
several OS (Windows included).

I think we really need to take care of beginners who would like to install
postgres on their laptop to "give it a try".

What do you think ?

Cheers,

Lætitia

--
*Think! Do you really need to print this email ? *
*There is no Planet B.*

Responses

Browse pgsql-docs by date

  From Date Subject
Next Message Jürgen Purtz 2019-02-12 08:19:46 Re: Tutorial section of documentation: enhancements needed
Previous Message Michael Paquier 2019-02-12 03:05:59 Re: Ancient comment in rules.sgml