Обсуждение: Tutorial section of documentation: enhancements needed

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> 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