Tutorial section of documentation: enhancements needed

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Tutorial section of documentation: enhancements needed

Lætitia Avrot
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.
Reply | Threaded
Open this post in threaded view
|

Re: Tutorial section of documentation: enhancements needed

Jürgen Purtz
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



Reply | Threaded
Open this post in threaded view
|

Re: Tutorial section of documentation: enhancements needed

Jonathan S. Katz-3
In reply to this post by Lætitia Avrot
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


signature.asc (849 bytes) Download Attachment
Reply | Threaded
Open this post in threaded view
|

Re: Tutorial section of documentation: enhancements needed

Thomas Munro-3
On Fri, Feb 15, 2019 at 12:57 PM Jonathan S. Katz <[hidden email]> 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> 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?)

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:

https://www.postgresql.org/message-id/CAEepm%3D1P0WD_g%3DELNmBJFhwKuCjYZOi4p4rutKj3kw7QneLB2A%40mail.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