PostgreSQL project
Stay organized with collections
Save and categorize content based on your preferences.
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)
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.
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.
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.
Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License. For details, see the Google Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2024-11-08 UTC.
[[["Easy to understand","easyToUnderstand","thumb-up"],["Solved my problem","solvedMyProblem","thumb-up"],["Other","otherUp","thumb-up"]],[["Missing the information I need","missingTheInformationINeed","thumb-down"],["Too complicated / too many steps","tooComplicatedTooManySteps","thumb-down"],["Out of date","outOfDate","thumb-down"],["Samples / code issue","samplesCodeIssue","thumb-down"],["Other","otherDown","thumb-down"]],["Last updated 2024-11-08 UTC."],[[["\u003cp\u003eThis project aims to update the PostgreSQL introductory tutorial, focusing on improving the installation and setup process for beginners.\u003c/p\u003e\n"],["\u003cp\u003eThe project will revamp the tutorial's structure, providing a comprehensive introduction to PostgreSQL concepts like client-server architecture and database clusters.\u003c/p\u003e\n"],["\u003cp\u003eInstallation instructions will be enhanced to cover both source and binary options, addressing common setup challenges faced by new users.\u003c/p\u003e\n"],["\u003cp\u003eThe tutorial will empower users to independently create and access databases, simplifying instructions and providing solutions for typical authentication issues.\u003c/p\u003e\n"],["\u003cp\u003eThe project involves practical testing, community feedback analysis, and expert consultation to ensure clarity, accuracy, and relevance of the updated tutorial.\u003c/p\u003e\n"]]],["The project involves updating the PostgreSQL introductory tutorial for beginners. Key actions include converting the Architectural Fundamentals chapter into a comprehensive introduction, updating the Installation tutorial to cover both source and binary options, and outlining post-installation steps like initializing the cluster and starting the server. It also involves improving the create and access database tutorials by providing actionable solutions and explaining authentication basics, while aiming to minimize reliance on administrator consultation. The writer will test the tutorial on Windows and Ubuntu, and consult mentors.\n"],null,["This page contains the details of a technical writing project accepted for\nGoogle Season of Docs.\n\nProject summary\n\nOpen source organization:\n: PostgreSQL\n\nTechnical writer:\n: lu\n\nProject name:\n: Introductory Tutorial\n\nProject length:\n: Standard length (3 months)\n\nProject description\n\nUpdate introductory tutorial to improve PostgreSQL installation and setup experience for beginners.\n(\u003chttps://www.postgresql.org/docs/current/tutorial-start.html\u003e)\n\n1. Convert the Architectural Fundamentals chapter into a comprehensive introduction to PostgreSQL tutorials (\u003chttps://www.postgresql.org/docs/current/tutorial-arch.html\u003e). 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.\n\n2. Update Installation tutorial (\u003chttps://www.postgresql.org/docs/current/tutorial-install.html\u003e).\n\n - Advertise both source and binary install options. Add reference to \u003chttps://www.postgresql.org/download/\u003e that offers minimal binary install instructions.\n - Identify gaps in binary install instructions, if any, and either expand the website or address them in documentation.\n - 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.\n - 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.\n3. Improve \u003chttps://www.postgresql.org/docs/current/tutorial-createdb.html\u003e\n\n - 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.\n4. Improve \u003chttps://www.postgresql.org/docs/current/tutorial-accessdb.html\u003e\n\n - Explain basic issues related to authentication and trivial pg_hba.conf examples\n\nTo 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."]]
