Suggestion to improve PostgreSQL documentation clarity
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/18/source-format.html
Description:
Hello PostgreSQL Documentation Team,
I am a PostgreSQL learner and community member. While studying PostgreSQL
documentation and working on database projects, I found that some sections
could benefit from additional beginner-friendly explanations and practical
examples.
I suggest adding more step-by-step examples for new users, especially around
database setup, connection configuration, user privileges, security
settings, and common migration workflows.
Clear examples showing real-world scenarios would help learners and
developers understand PostgreSQL concepts more easily and reduce confusion
when applying the documentation in practice.
Thank you for maintaining excellent PostgreSQL documentation and for
considering this suggestion.
Best regards,
Bilal Abdulkadir Muhammed
On Sun, 2026-07-12 at 16:09 +0000, PG Doc comments form wrote:
I am a PostgreSQL learner and community member. While studying PostgreSQL
documentation and working on database projects, I found that some sections
could benefit from additional beginner-friendly explanations and practical
examples.I suggest adding more step-by-step examples for new users, especially around
database setup, connection configuration, user privileges, security
settings, and common migration workflows.
I am not certain if the documentation is the correct place for that.
There is a difference between documentation and a tutorial, and mixing
them won't be a service to anybody.
Now the documentation already contains examples, and those are clearly
fine (and more of them might be appropriate occasionally).
But step-by-step examples for new learners wouldn't be good.
However, the documentation contains a small tutorial, and there your
proposed additions would be fine.
Yours,
Laurenz Albe