דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- מוג'ה גלובלי
- כתב טכני:
- טלזיפנדה
- שם הפרויקט:
- תיעוד של המדריך הטכני לקליטת שותפים של FLINT
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
תיעוד של המדריך הטכני לקליטת שותפים של FLINT, שמספק הדרכה לתורמים החדשים בתהליך הקליטה הטכני. כך יוכלו שותפים חדשים להתחיל לעבוד בקלות עם תמיכה מינימלית מתחזקים.
בעיות בפרויקט
בהמשך מופיעה רשימה של הבעיות הקריטיות ביותר הקשורות לתיעוד הנוכחי: - חלקים לא מאורגנים של הוראות במדריך ההגדרה המקומי, באופן שמקשה על תורם תוכן חדש להתחיל בעבודה. - קיימים מספר מאגרים של FLINT שאין בהם תיעוד לגבי המטרה שלהם, והם אינם מקושרים זה לזה, ולכן קשה למשתמש החדש לזהות את המאגר שיש להתקין. - ההתקנה של Windows מתועדת היטב, אבל תיעוד ההתקנה מבוסס Linux יש מקום לשיפור. - זרימת העבודה של Git אינה כלולה כרגע בתיעוד
הפתרון המוצע
ההצעה הזו היא פתרון להדרכה של השותפים החדשים בתהליך קליטת שותף טכני, כך שתורמים חדשים יוכלו להתחיל בקלות עם תמיכה מינימלית מתחזקים. כדי לעשות זאת, אפשר לארגן מחדש את התיעוד הקיים כדי שיהיה ידידותי למתחילים ולתחזק מאגר עצמאי מרכזי לכל המסמכים הזמינים. הפרויקט מחולק לשלושה שלבים:- - סקירת התיעוד הקיים וארגון הקוד מחדש: מטרת השלב הזה היא לבדוק את המדריך הנוכחי ולשקלל אותו מחדש כך ששותפים חדשים יוכלו להבין אותו בצורה תמציתית. בנוסף, צריך לשנות את המסמכים כדי שהתוכן יהיה ידידותי יותר למתחילים, כך שיהיה אפשר להוסיף תגים, סמלי אמוג'י ומידע על בעיות שמסומנות בתגים של משתמשים ראשוניים בלבד או תגים של בעיות ראשונות. - יצירת מאגר מסמכים עצמאי מרכזי: מטרת השלב הזה היא לקשר את כל התיעוד הזמין בסדר לוגי רציף במאגר עצמאי. זה כולל סידור של ההנחיות לתרומות, ההוראות להגדרת הפרויקט ומדריכים מפורטים. - הוספת תהליך העבודה של המפתחים ואתר הקהילה למפתחים חדשים: מטרת השלב הזה היא להוסיף את תהליך העבודה של המפתחים שכולל את ההנחיות לתרומת git ואת הארכיטקטורה הטכנית של הפרויקט, יחד עם הנחיות לבדיקות ובקרת איכות. אתר הקהילה המוצע יהיה אפליקציה בדף יחיד שמציגה את תהליך העבודה, בעיות של משתמשים חדשים ורשימה של כל השותפים ביצירת התוכן שדרכם אפשר להצהיר בעלות עליהן. שלב 1: סקירת התיעוד הקיים וארגון הקוד מחדש:
משנים את התיעוד הנוכחי של המאגרים הבאים: - FLINT: התיעוד הנוכחי אינו מפורט מאוד ולא מספק סדר רציף של ספריות נדרשות. מדריכי ההוראות המפורטים מחולקים לקובצי PDF שונים, אך ניתן לאחד אותם במקום אחד ובצורה תמציתית יותר. בנוסף, מדריכי ההתקנה מותאמים לחלונות, אך הפניית התקנה של Linux אל המאגר FLINT.docker יכולה להועיל. - FLINT.docker: המסמך הנוכחי לא מספק את המטרה של הגדרת המאגר, שנועד לספק התקנת Linux של FLINT דרך עגינה. התמיכה באמצעות עגינה מוגבלת ל-Ubuntu 18.04 (Bionic Beaver) בלבד, אך ניתן להרחיב אותה להפצות אחרות המבוססות על Linux. התיעוד הנוכחי גם צריך לשים דגש על האופן הרציף של הגדרת קובצי ה-Dockerfiles, וכן מידע מספיק על אופן הבנייה מ-Makefile. - FLINT.example: בתיעוד הנוכחי לא מוצגת המטרה של הגדרת המאגר, והוא נועד לספק דוגמה לאופן השימוש ב-FLINT. אפשר להפריד בצורה טובה יותר בין ההפעלות לדוגמה השונות לפי הוראות ספציפיות להפעלתן. אנחנו צריכים גם לקשר את המאגר הזה למאגר FLINT הראשי שלנו, שמספק למשתמשים אפשרות לנווט לכאן כדי לבדוק את הדוגמה בפועל.
צריך להוסיף למסמכי התיעוד הנוכחיים את הפרטים הבאים: - שימוש ב-Git וב-GitHub. ההסברים יכללו הוראות מפורטות ל-fork, לשכפל ולאחר מכן להגדיר את ה-upstream של המאגר. כמו כן, יוסבר בו איך לבצע rebase מול המאסטר העדכני ביותר ולטפל בהתנגשויות מיזוג. - תגים ואמוג'י: בתיעוד הנוכחי חסרים תגים וסמלי אמוג'י, שיכולים לעזור לתורמים החדשים להרגיש שהם מקבלים בברכה את הבעיות פחות מפחידות. - מידע לגבי המתחילים/בעיות שמתאימות למתחילים: קישור זה יעזור להפנות את התורמים החדשים לנושאים המתאימים למתחילים ולאתר הקהילה. - מידע על המאגר Import-me: המאגר Import-me פועל כתבנית בסיס להנעת כל מאגר Moja Global. בתיעוד הנוכחי אין אזכור של חשיבות לנושא הזה. צריך לעדכן אותו כך שיכלול את המאגר של Import-me, וצריך להוסיף גם את השלבים לבחירה באפשרות הזו כתבנית ליצירת מאגר חדש. בנוסף, צריך להיות נוהל למתכנתים כדי להציע תכונות נוספות למאגר Import-me.
שלב 2: יצירת מאגר מסמכים מרכזי עצמאי
כלי לשימוש עבור פלטפורמת האירוח:
הכלים המוצעים לפלטפורמת אירוח זו הם Read The Docs מהסיבות הבאות:- - דירוג גבוה בקרב פלטפורמות אירוח שונות. - עדכון אוטומטי בדחיפה של שמירה - מאחר שהקהילה הגדולה משתמשת בו בקלות, תמיכה קלה להגדרה ולפתרון בעיות - התיעוד נעשה באמצעות reStructuredText, והפלט נוצר על ידי Sphinx.
ארגנו את כל התוכן בסדר רציף לוגי:
סדר התוכן המוצע הוא:- - מבוא למסמכי תיעוד למפתחים: בסעיף זה תעסוק במבוא ל-Moja Global ול-FLINT. - הוספת תוכן: חלק זה יכלול את סעיפי המשנה 'דרכים נוספות לתרומה' (מבחינת קוד/דיווח על באגים/תרגום/תיעוד/ארגון אירועים וכו') ו'קוד התנהגות'. - הגדרת פיתוח: החלק הזה יכלול סעיפי משנה: 'תהליך העבודה ב-Git & GitHub', 'התקנת Windows', 'התקנת Linux', ולאחר מכן ביצוע של תהליך עבודה למפתחים בתהליך העבודה הבא: - הצטרפות אלינו: בקטע הזה יופיעו הפורומים השונים ברשתות החברתיות, כמו ערוצי Slack, כדי ליצור קשר עם Moja Global ולעבוד עליה.
שלב 3: הוספת תהליך העבודה של המפתח ואתר הקהילה לתורמים חדשים:
תיעוד של תהליך העבודה למפתחים:
מסמכי התיעוד של תהליך העבודה למפתחים יכללו את פרקי המשנה הבאים:
- סטאק התוכנות/הארכיטקטורה שבהן נעשה שימוש והמודולים השונים בקוד: תיעוד להיכרות עם סטאק התוכנות החדש ליישום סטאק התוכנות, הספריות והמודולים השונים של בסיס הקוד.
- כלי הבדיקה והכיסוי המשולבים: הוספנו עוד תורמים חדשים לצינור עיבוד הנתונים של CI/CD, המשמשים לבדיקות, בוטים של כיסוי ובדיקות איכות אוטומטיות פועלות מול הקוד שלהם. מתן הנחיות גם למי לפנות אם הבחינות נכשלות.
- בוטים שנועדו להקל על תהליך העבודה, למשל: Zulipbot: עיצוב תבניות תוכן להצגה של הבוטים ומסמכי תיעוד שיהיו זמינים כדי לאפשר למשתמשים להבין את הבוטים ואפילו לשפר את הגדרות הבוט על ידי הוספת תוכן.
- בדיקה ושליחה ידנית של בקשת משיכה: תיעוד שיש לספק לגבי בדיקה ידנית של בקשות משיכה לסטנדרטים מסוימים והעלאת התוצאות במונחים של צילומי מסך או קובצי GIF בשליחה של בקשות משיכה.
- משיכת הנחיות לבדיקה של בקשות ששולחים ותומכים בהן: הנחיות לתיוג צוותים מסוימים לבדיקה ולהוספת תוויות כמו 'נדרש בדיקה' לבקשת השליחה, כדי לאפשר לבעלי המקצוע להשיב.
אתר הקהילה:
אתר הקהילה יכלול את התכונות הבאות:-
- מידע על תהליך העבודה שלנו: תהליך העבודה יכלול סדרת פעולות שתורם תוכן חדש יוכל להתחיל בהן, למשל: תביעת בעלות על בעיה ראשונה בטיימר, לאחר מכן יצירה של בעיה ראשונה בטיימר עבור מישהו אחר ועזרה לאחרים על ידי שליחת משוב ובדיקת בקשות המשיכה שלהם.
- רשימת בעיות שקשורות לטיימר הראשון בלבד: רשימת הבעיות שמיועדות באופן ספציפי למשתמשים חדשים או לתורמים חדשים.
- רשימת בעיות לא עדכניות: רשימת הבעיות שלא עבדו עליהן במשך תקופה ארוכה, ולכן הן זמינות לבחירה על ידי תורמים.
- רשימת תורמים: רשימת התרומה שתרמו עד כה למאגרים של Moja Global.
- תורמים אחרונים: רשימת תורמים שתרמו לאחרונה למאגרים של Moja Global.
- קישורים להצטרפות לפורומים של צ'אטים: מידע וקישורים להצטרפות לקהילת Slack, כדי לקבל תשובות לשאלות שלהם ולדיונים נוספים על הפרויקטים.