דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- GenPipes
- כתב טכני:
- שלו
- שם הפרויקט:
- יש להגדיר מסמכי GenPipes בדף 'Read The Docs'
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
אני מציע תוכנית שכוללת 3 שלבים להשגת המטרה של הגדרת תיעוד של GenPipes ב-'Read The Docs'.
שלב 1: איש קשר
כדאי לעיין במסמכים הקיימים של GenPipes כמשתמש או כחוקר חדש
- זיהוי מידע חסר או אי-דיוקים
- הצעת נושאים חדשים למסמכים (אם נדרש)
- טיוטה של ארכיטקטורה של מידע במטרה להתאים לקהל היעד, בהתמקדות במשתמשים חדשים.
(הערה: במהלך השלב הזה, יכול להיות שנצטרך גם מידע ממנטורים של GenPipes לגבי הגדרה חדשה של מאגר GitHub שבו אפשר לארח מסמכי genpipes עבור RTD. מאגר זה של GitHub יכול לשמש לייבוא כל המסמכים בצינורות עיבוד נתונים של RTD build. יכול להיות שיהיה צורך בתובנות לגבי כללי המאגר ב-GenPipes והנחיות לניהול מקורות של מסמכים, אם יש כאלה. אחרת, ניתן להשתמש באותיות רגילות. בנוסף, בשביל איש הקשר, אוכל להדגים הגדרה של מאגר RTD לדוגמה באמצעות חשבון GitHub שלי.למשל, https://gpdocs.readthedocs.io/en/latest/ – זו דוגמה של מאגר RTD שיצרתי להצעה הזו).
בהתאם לבדיקה ולניתוח שבשלב הקודם, צרו שלד של ברבון של מבנה / האינדקס של מסמכי ה-GenPipes והציבו אותו באתר RTD
- פעולה זו כוללת יצירה של מאגר GitHub (למשל באמצעות כלים של Sphinx) וקובצי תיעוד בסיסיים
- זה כולל גם יצירת TOC חדשה שמביאה בחשבון גם משתמשים חדשים וגם שימושים מנוסים, בקטעים שונים או בתהליכי מידע שונים.
בדיקה / קבלת אישור לגבי TOC בשלד של עצמות
במהלך שלב ההערכה של GenPipes ב-GSoD ניסיתי ליצור ערך עבור GenPipes באמצעות הדוגמה הזו שמתארחת ב-RTD. שימו לב: הסרטון הזה מיועד למטרות הדגמה בלבד. זהו קישור מוגן, שעדיין לא גלוי לכולם ב-RTD. גם אם אוסיף לרשימת המועמדים הסופית, תוכלו להשתמש בהדגמה הזו כדי להניע את מאמצי ה-RTD ב-GenPipes. כבר ביררתי את המקורות במאגר c3g/GenPipes ב-GitHub. המנטורים, רולה והקטור אהבו את הסרטון בדיון של 'שיתוף המסך' ב-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 (בנייה של ספינקס) לגבי האופן שבו משתמשים יכולים לתחזק מסמכים ב-GenPipes ולערוך אותם, ואם C3G יאפשר זאת לתורמים חיצוניים של מסמכים. יכול להיות שתצטרכו ליצור הנחיות לעדכוני מסמכים בדומה להנחיות בנושא תכנות. יכול להיות שיידרשו עוד שלבי משנה. למשל, אפשר לבצע אוטומציה של בדיקת האיות לפני אישור של מחלקת יחסי הציבור במסמכי GenPipes.
דיווח
לבסוף, צרו דוח ל-GSoD המבוסס על חוויות, יומנים ומשוב ממנטורים.
מחשבות אחרות
בעתיד (אחרי 3 חודשים), אם זה רלוונטי, אוכל לעזור לנהל את הפעילות הזו עבור GenPipes לטווח ארוך יותר. או להדריך אחרים, אם צריך, לבצע את אותו השלב. אנחנו יכולים להגיע להחלטה הזו על סמך התוצאות של 3 החודשים הראשונים.
כדאי גם להציע רעיון נוסף להצעת פרויקט – יצירה של תקציר דף של GenPipes 3 שיעזור להתחיל את התהליך בקלות. כיום, משתמשים חדשים צריכים לקפוץ סלים רבים לפני שיתחילו להשתמש ב-GenPipes, מכיוון שהתיעוד טוב אך מפוזר ולא מועיל למשתמשים חדשים. לא בטוח אם ניתן לעשות זאת תוך 3 חודשים, אבל הייתי רוצה לנסות ולהתנסות.
ניתן לעיין גם בהצעה הזו ובאופן שבו היא הושגה (היסטוריה) בכתובת https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing