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