בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- PostgreSQL
- כותבים טכניים:
- lu
- שם הפרויקט:
- מדריך למתחילים
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
עדכנו את המדריך למתחילים כדי לשפר את חוויית ההתקנה וההגדרה של PostgreSQL למתחילים. (https://www.postgresql.org/docs/current/tutorial-start.html)
ממירים את פרק 'יסודות הארכיטקטורה' למבוא מקיף למדריכי PostgreSQL (https://www.postgresql.org/docs/current/tutorial-arch.html). אפשר להרחיב על ארכיטקטורת שרת-לקוח, על psql כדוגמה ללקוח שנעשה בו שימוש במדריך הזה, על המונח ""אשכול"" בהקשר של PostgreSQL, על משתמשים ובעלות ב-DB לעומת משתמשים ובעלות ב-OS.
מעדכנים את מדריך ההתקנה (https://www.postgresql.org/docs/current/tutorial-install.html).
- כדאי לפרסם גם את אפשרויות ההתקנה של המקור וגם את האפשרויות של ההתקנה הבינארית. מוסיפים הפניה לכתובת https://www.postgresql.org/download/, שבה מפורטות הוראות התקנה בינאריות מינימליות.
- מזהים פערים בהוראות ההתקנה הבינאריות, אם יש כאלה, ומרחיבים את האתר או מטפלים בהם במסמכי העזרה.
- אל תצפו שהמשתמשים יקראו את הפרק המלא בנושא התקנה מקוד מקור וימצאו את הדרך בעצמם: כדאי לתאר את השלבים העיקריים הנדרשים לאחר ההתקנה, כמו איפוס האשכולות והפעלה (אוטומטית) של השרת. אם רלוונטי, אפשר לספק קישורים לפרקים ספציפיים במסמכי התיעוד.
- מוסיפים קישורים למקורות מידע רלוונטיים שמרחיבים על ברירת המחדל ועל השיטות המומלצות למערכת הפעלה מסוימת, אם יש כאלה שהקהילה מכירה בהם.
שיפור https://www.postgresql.org/docs/current/tutorial-createdb.html
- ככל האפשר, מומלץ להסיר הוראות מסוג ""יש לפנות לאדמין"", ולספק פתרונות פרקטיים על סמך ההנחה שהמשתמש פעל לפי המדריך שלב אחר שלב.
לשפר את https://www.postgresql.org/docs/current/tutorial-accessdb.html
- הסבר על בעיות בסיסיות שקשורות לאימות ודוגמאות טריוויאליות של pg_hba.conf
כדי לספק את התיקון הזה לתיעוד, אני מתכוון לנסות את המדריך הנוכחי ל-Windows ו-Ubuntu, לעיין בפורומים בנושא בעיות הגדרה נפוצות ולהתייעץ עם מנטורים כדי לוודא שהבנתי את השיטות המומלצות ושהמושגים החשובים ביותר מוסברים ללא צורך לפשט את התהליך.