בדף הזה מופיעים הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Docs ל-Google Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- GenPipes
- כותבים טכניים:
- shaloo
- שם הפרויקט:
- הגדרת מסמכי GenPipes ב-Read The Docs
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
אני מציע תוכנית בת 3 שלבים להשגת היעד של הגדרת מסמכי העזרה של GenPipes ב-'Read The Docs'.
שלב 1: איש קשר
משתמשים חדשים או חוקרים יכולים לעיין במסמכי התיעוד הקיימים של GenPipes
- זיהוי מידע חסר או לא מדויק
- להציע נושאים חדשים למסמכים (אם צריך)
- ניסוח של מפת ארכיטקטורת המידע כדי לטפל בקהל היעד, עם דגש על משתמשים חדשים.
(הערה: בשלב הזה, יכול להיות שנצטרך גם משוב מהמנחים של GenPipes בנוגע להגדרה של מאגר חדש ב-GitHub שבו אפשר יהיה לארח מסמכים של GenPipes ל-RTD. אפשר להשתמש במאגר הזה ב-GitHub כדי לייבא את כל המסמכים בצינורות עיבוד נתונים ל-build של RTD. יכול להיות שיידרשו תובנות לגבי כללי מאגרי GenPipes והנחיות לניהול מקורות מסמכים אם צריך לפעול לפיהם. אחרת, אפשר להשתמש בעמודות הרגילות, afaik. בנוסף, לצורך הוכחת היתכנות, אוכל להדגים הגדרה לדוגמה של מאגר RTD באמצעות חשבון GitHub שלי – לדוגמה, https://gpdocs.readthedocs.io/en/latest/ – זהו מאגר לדוגמה שיצרתי עבור ההצעה הזו)
על סמך הבדיקה והניתוח בשלב הקודם, יוצרים שלד בסיסי של המבנה או המדד המוצעים למסמכי התיעוד של GenPipes ומעלים אותו לאתר RTD
- השלבים האלה כוללים יצירת מאגר ב-GitHub (לדוגמה, באמצעות הכלים של Sphinx) וקובצי תיעוד בסיסיים.
- התהליך כולל גם יצירה של תוכן חדש של תוכן מפורט, שמותאם גם למשתמשים חדשים וגם למשתמשים מנוסים, בקטעים שונים או בזרימות מידע שונות.
בדיקה או קבלת אישור על תוכן עניינים בסיסי
במהלך שלב ההערכה של GenPipes GSoD, ניסיתי ליצור ערך ל-GenPipes באמצעות הדוגמה הזו שמתארחת ב-RTD. לתשומת ליבך, זהו קישור מוגן למטרות הדגמה בלבד, והוא עדיין לא מופיע באופן ציבורי ב-RTD. גם אם לא נכלל ברשימת המועמדים הסופית, אפשר להשתמש בהדגמה הזו כדי להתניע את מאמצי ה-RTD של GenPipes. כבר העברתי את המקורות למאגר GitHub של c3g/GenPipes. למנטורים, רולה והקטור, הסרטון מאוד אהב במהלך השיחה ב-Skype עם שיתוף המסך מוקדם יותר, ולכן חשבתי שה-GSoD Gods ירצו לראות אותו גם כן. כרגע זה רק השלד, אבל אני מתכנן לעדכן אותו כשיהיה לי זמן עד 30 ביולי.
https://genpipes.readthedocs.io/en/latest/
שלב 2: יצירת קבוצת מסמכים של GenPipes Doc v0.9
זיהוי מסמכי GenPipes קיימים או עדכניים שאפשר לייבא, לקשר או להמיר למסמכי עזרה מבוססי Sphinx/rst לצורך אירוח ב-RTD, תוך התחשבות בלוחות הזמנים של GSoD
ממירים את המסמכים שזוהו לפורמט rst, אם צריך, יוצרים מסמכים חדשים במקרים הרלוונטיים ומשתמשים מחדש בכל מה שאפשר או שזה רלוונטי.
- מייבאים את קבוצת המסמכים הראשונית הזו ל-ReadTheDocs כרעיון להמחשה (Proof of Concept) – ומארחים אותה שם כמאגר מוגן. מומלץ להוסיף הערה מראש ולציין למשתמשים חדשים לעבור לתיעוד המקורי של GenPipes עד לקבלת אישור לבדיקה או למעבר הרשמי.
בדיקה, תיקון או עדכון
שלב 3: משפרים, בודקים ומפרסמים את הטיוטה הראשונה ב-RTD
ממלאים את הפרטים של המבנה החדש של מסמכי GenPipes בהקדמה של GenPipes – מוסיפים מסמכים נוספים מלבד הראשונים (Readme של GenPipes), מושגים, מדריכים וכו'.
מומלץ להוסיף סימון ברור בתוכן העניינים כדי לטפל במשתמשים חדשים, במשתמשים מנוסים ב-GenPipes, במפתחים של GenPipes וכו'.
להציע ולדון בתהליך עבודה עם אוטומציה חלקית באמצעות RTD (פיתוח של Sphinx) לגבי האופן שבו אפשר לתחזק ולערוך את קבוצת המסמכים של GenPipes על ידי משתמשים, ואם C3G תאפשר זאת לכותבי מסמכים חיצוניים. יכול להיות שיהיה צורך ליצור הנחיות מסוימות לעדכוני מסמכים, בדומה להנחיות לכתיבת קוד. יכול להיות שיידרשו עוד שלבים משניים. לדוגמה: מומלץ לבצע אוטומציה של בדיקת האיות לפני אישור ה-PR במסמכי GenPipes.
דיווח
לבסוף, יוצרים דוח ל-GSoD על סמך חוויות, יומנים ומשוב ממנטורים.
מחשבות נוספות
בעתיד (אחרי 3 חודשים), אם רלוונטי, אוכל לעזור לך לשמור על העדכון של GenPipes לטווח ארוך יותר. או ללמד אחרים לעשות את זה, אם צריך. נוכל להבין זאת על סמך התוצאות של 3 החודשים הראשונים.
בנוסף, רציתי להציע רעיון נוסף להצעת פרויקט – יצירת תקציר של 3 דפים בנושא GenPipes שיעזור בתהליך ההצטרפות. היום, משתמשים חדשים צריכים לעבור הרבה שלבים לפני שהם יכולים להתחיל להשתמש ב-GenPipes, כי המסמכים מועילים אבל מפוזרים ולא מתאימים למשתמשים חדשים. לא בטוח שאפשר לעשות את זה תוך 3 חודשים, אבל אנסה.
אפשר לראות את ההצעה הזו ואת האופן שבו היא הפכה (היסטוריה) גם בכתובת https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing