This page contains the details of a technical writing project accepted for Season of Docs.
- Open source organization:
- Technical writer:
- Project name:
- Introductory Tutorial
- Project length:
- Standard length (3 months)
Update introductory tutorial to improve PostgreSQL installation and setup experience for beginners. (https://www.postgresql.org/docs/current/tutorial-start.html)
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.
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.
- 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.
- 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.