PostgreSQL project

  • This project aims to update the PostgreSQL introductory tutorial, focusing on improving the installation and setup process for beginners.

  • The project will revamp the tutorial's structure, providing a comprehensive introduction to PostgreSQL concepts like client-server architecture and database clusters.

  • Installation instructions will be enhanced to cover both source and binary options, addressing common setup challenges faced by new users.

  • The tutorial will empower users to independently create and access databases, simplifying instructions and providing solutions for typical authentication issues.

  • The project involves practical testing, community feedback analysis, and expert consultation to ensure clarity, accuracy, and relevance of the updated tutorial.

This page contains the details of a technical writing project accepted for Google Season of Docs.

Project summary

Open source organization:
PostgreSQL
Technical writer:
lu
Project name:
Introductory Tutorial
Project length:
Standard length (3 months)

Project description

Update introductory tutorial to improve PostgreSQL installation and setup experience for beginners. (https://www.postgresql.org/docs/current/tutorial-start.html)

  1. Convert the Architectural Fundamentals chapter into a comprehensive introduction to PostgreSQL tutorials (https://www.postgresql.org/docs/current/tutorial-arch.html). Possible things to expand on are client-server architecture, psql as a client example to be used in this tutorial, ""cluster"" terminology in PostgreSQL context, DB vs OS users and ownership.

  2. Update Installation tutorial (https://www.postgresql.org/docs/current/tutorial-install.html).

    • Advertise both source and binary install options. Add reference to https://www.postgresql.org/download/ that offers minimal binary install instructions.
    • Identify gaps in binary install instructions, if any, and either expand the website or address them in documentation.
    • Do not rely on users reading the full source-install chapter and figuring it out: outline the main steps required after the install, such as initializing the cluster and (auto)starting the server. Provide links to specific Documentation chapters for more details where applicable.
    • Add see-also links to relevant resources that expand on defaults and best practices for a particular OS, if there are any recognized by the community.

  3. Improve https://www.postgresql.org/docs/current/tutorial-createdb.html

    • Get rid of ""consult the administrator"" instructions wherever possible; provide actionable solutions based on the assumption that the user followed the tutorial step-by-step.

  4. Improve https://www.postgresql.org/docs/current/tutorial-accessdb.html

    • Explain basic issues related to authentication and trivial pg_hba.conf examples

To provide this documentation patch, I intend to try out the current tutorial on Windows and Ubuntu, browse forums for frequent setup issues, and consult mentors to ensure I get the best practices right and the most important concepts are explained without oversimplification.