# PostgreSQL project

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.