pg.ddx.io pgsql-docs@postgresql.org mailing list archive
help / color / mirror / Atom feedTutorial section of documentation: enhancements needed
4+ messages / 4 participants
[nested] [flat]
* Tutorial section of documentation: enhancements needed
@ 2019-02-12 08:06 Lætitia Avrot <laetitia.avrot@gmail.com>
2019-02-12 08:19 ` Re: Tutorial section of documentation: enhancements needed Jürgen Purtz <juergen@purtz.de>
2019-02-14 23:57 ` Re: Tutorial section of documentation: enhancements needed Jonathan S. Katz <jkatz@postgresql.org>
0 siblings, 2 replies; 4+ messages in thread
From: Lætitia Avrot @ 2019-02-12 08:06 UTC (permalink / raw)
To: 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.*
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Tutorial section of documentation: enhancements needed
2019-02-12 08:06 Tutorial section of documentation: enhancements needed Lætitia Avrot <laetitia.avrot@gmail.com>
@ 2019-02-12 08:19 ` Jürgen Purtz <juergen@purtz.de>
1 sibling, 0 replies; 4+ messages in thread
From: Jürgen Purtz @ 2019-02-12 08:19 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org
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
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Tutorial section of documentation: enhancements needed
2019-02-12 08:06 Tutorial section of documentation: enhancements needed Lætitia Avrot <laetitia.avrot@gmail.com>
@ 2019-02-14 23:57 ` Jonathan S. Katz <jkatz@postgresql.org>
2019-02-17 22:20 ` Re: Tutorial section of documentation: enhancements needed Thomas Munro <thomas.munro@enterprisedb.com>
1 sibling, 1 reply; 4+ messages in thread
From: Jonathan S. Katz @ 2019-02-14 23:57 UTC (permalink / raw)
To: Lætitia Avrot <laetitia.avrot@gmail.com>; pgsql-docs
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
Attachments:
signature.asc (application/pgp-signature, 832B) download
^ permalink raw reply [nested|flat] 4+ messages in thread
* Re: Tutorial section of documentation: enhancements needed
2019-02-12 08:06 Tutorial section of documentation: enhancements needed Lætitia Avrot <laetitia.avrot@gmail.com>
2019-02-14 23:57 ` Re: Tutorial section of documentation: enhancements needed Jonathan S. Katz <jkatz@postgresql.org>
@ 2019-02-17 22:20 ` Thomas Munro <thomas.munro@enterprisedb.com>
0 siblings, 0 replies; 4+ messages in thread
From: Thomas Munro @ 2019-02-17 22:20 UTC (permalink / raw)
To: Jonathan S. Katz <jkatz@postgresql.org>; +Cc: Lætitia Avrot <laetitia.avrot@gmail.com>; pgsql-docs
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...
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
^ permalink raw reply [nested|flat] 4+ messages in thread
end of thread, other threads:[~2019-02-17 22:20 UTC | newest]
Thread overview: 4+ messages (download: mbox mbox.gz follow: Atom feed)
-- links below jump to the message on this page --
2019-02-12 08:06 Tutorial section of documentation: enhancements needed Lætitia Avrot <laetitia.avrot@gmail.com>
2019-02-12 08:19 ` Jürgen Purtz <juergen@purtz.de>
2019-02-14 23:57 ` Jonathan S. Katz <jkatz@postgresql.org>
2019-02-17 22:20 ` Thomas Munro <thomas.munro@enterprisedb.com>
This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox