Tutorial section of documentation: enhancements needed
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.*
On 12.02.19 09:06, Lætitia Avrot wrote:
I think we really need to take care of beginners who would like to
install postgres on their laptop to "give it a try".
+1
Hi Laetitia,
On 2/12/19 3:06 AM, Lætitia Avrot wrote:
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 <http://postgresql.org> website
I don't know if we need to change the name as much as it needs some
rewriting. Perhaps the whole section is simplified to a "getting
started" that gets people to download, install, and run PostgreSQL in
their desired environment, and then the basic commands to get started
(which I think we do a decent job of that portion?)
In my early days of using PostgreSQL, I remember this being in my
bookmarks for getting started:
https://www.postgresql.org/docs/current/install-short.html
Perhaps we can also boil something down for the modern methods of
installation.
Also I would not necessarily say this is a "millennial" issue, I think
this extends to many new users of PostgreSQL who, in particular, may not
be as used to the command-line. (I also say that as someone who is
technically considered a millennial ;-)
- 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 <http://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).
+1. One thing to consider is that many people also use something like
pgAdmin (I've often heard people thing pgAdmin is PostgreSQL) which also
adds to the how people get started.
I think we really need to take care of beginners who would like to
install postgres on their laptop to "give it a try".
A section that was added as part of the website update last year and
subsequently poorly named by me was this:
https://www.postgresql.org/docs/online-resources/
Which contains a list of tutorials and other resources to help get
started with PostgreSQL. We could give this page a better name in the
hope that it helps people with more of the "getting started" pieces
until if/when we change the docs.
Thanks,
Jonathan
On Fri, Feb 15, 2019 at 12:57 PM Jonathan S. Katz <jkatz@postgresql.org> wrote:
On 2/12/19 3:06 AM, Lætitia Avrot wrote:
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 <http://postgresql.org> websiteI don't know if we need to change the name as much as it needs some
rewriting. Perhaps the whole section is simplified to a "getting
started" that gets people to download, install, and run PostgreSQL in
their desired environment, and then the basic commands to get started
(which I think we do a decent job of that portion?)
I was just wondering about creating a "how to test a patch" Wiki page.
Something to point people at, instead of writing out this sort of
thing in emails:
/messages/by-id/CAEepm=1P0WD_g=ELNmBJFhwKuCjYZOi4p4rutKj3kw7QneLB2A@mail.gmail.com
The "Tools Sets" part of our documentation already gives how-to style
"apt-get this and that" instructions for various OSes.
As for the people using Windows who want to contribute, it sounds like
we need to fix PostgreSQL so that it works when you build it on WSL
(based on a report I heard that it doesn't work if you do that today,
at least with Ubuntu on WSL). Then they could use the same super
short how-to-get-start guides as everyone else (I think the guide for
setting up native Windows development tools would be considerably
longer, since AFAIK you can't yet do something as easy as "apt-get foo
bar baz" and start hacking, but I don't know).
--
Thomas Munro
http://www.enterprisedb.com