בדף הזה מופיעים הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Docs ל-Google Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- moja global
- כותבים טכניים:
- Tlazypanda
- שם הפרויקט:
- מסמכי תיעוד של המדריך הטכני לתחילת השימוש ב-FLINT
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
מסמכי תיעוד של המדריך הטכני להדרכה למשתמשים חדשים של פלורידה
בעיות בפרויקט
לפניכם רשימה של הבעיות החשובות ביותר שקשורות למסמכי התיעוד הנוכחיים: - הוראות לא מאורגנות במדריך להגדרה מקומית, ולכן קשה לתורם חדש להתחיל לעבוד. - במספר מאגרים של FLINT אין תיעוד של המטרה שלהם והם לא מקושרים זה לזה, ולכן קשה למשתמש חדש לזהות איזה מאגר צריך להתקין. - התקנה ב-Windows מתועדת היטב, אבל יש מקום לשיפור במסמכי התיעוד של התקנה מבוססת-Linux. - תהליך העבודה ב-Git לא נכלל כרגע במסמכי העזרה
הפתרון המוצע
ההצעה הזו מציגה פתרון להדרכה של התורמים החדשים באמצעות קליטה טכנית, כדי שתורמי תוכן חדשים יוכלו להתחיל לעבוד בקלות עם תמיכה מינימלית מהמנהלים. כדי לעשות זאת, צריך לבצע רפאקציה של המסמכים הקיימים כדי שיתאימו למתחילים, וגם לנהל מאגר מרכזי עצמאי לכל המסמכים הזמינים. הפרויקט מחולק לשלושה שלבים:- - בדיקה של המסמכים הקיימים ועיצוב מחדש: המטרה של השלב הזה היא לבדוק את המדריך הנוכחי ולעצב אותו מחדש כך שיהיה תמציתי וברור למשתתפים חדשים. צריך גם לשנות את המסמכים כדי שיתאימו יותר למתחילים. לשם כך, צריך להוסיף תגים, אמוג'י ומידע על בעיות שמסומנות בתגים 'למשתמשים חדשים בלבד' או 'בעיה טובה למתחילים'. - יצירת מאגר מסמכי עזרה מרכזי ועצמאי: מטרת השלב הזה היא לקשר את כל המסמכים הזמינים בסדר לוגי רציף במאגר עצמאי. התהליך הזה כולל את הסדר של ההנחיות לתרומות, הוראות להגדרת הפרויקט ומדריכים מפורטים. - הוספת תהליך עבודה של מפתחים ואתר קהילה למפתחים חדשים: מטרת השלב הזה היא להוסיף את תהליך העבודה למפתחים שמכיל את ההנחיות לתרומות ב-Git ואת הארכיטקטורה הטכנולוגית של הפרויקט, יחד עם הנחיות לבדיקות ולבקרת איכות. האתר של הקהילה המוצעת יהיה אפליקציה של דף אחד שבה יוצגו תהליך העבודה, בעיות למתחילים שתורמים חדשים יכולים לדווח עליהן ורשימת כל התורמים. שלב 1: בודקים את המסמכים הקיימים ומבצעים רפאקציה:
שינוי המסמכים הקיימים במאגרים הבאים: - FLINT: המסמכים הקיימים לא מפורטים מאוד ולא כוללים סדר כרונולוגי של ספריות קודמות שנדרשות. המדריכים המפורטים מחולקים לקובצי PDF שונים, אבל אפשר לאחד אותם במקום אחד באופן תמציתי יותר. בנוסף, מדריכי ההתקנה רלוונטיים לחלונות, אבל במקרה של התקנת Linux עם הפניה אוטומטית למאגר FLINT.docker יכול להיות להפיק תועלת. - FLINT.docker: במסמכים הנוכחיים לא מוסבר למה הוקם המאגר הזה, והמטרה שלו היא לספק את התקנת FLINT ל-Linux דרך docker. התמיכה באמצעות docker מוגבלת ל-Ubuntu 18.04 (Bionic Beaver) אבל ניתן להרחיב אותה להפצות אחרות שמבוססות על Linux. בנוסף, במסמכי התיעוד הנוכחיים צריך להדגיש את האופן המסודר להגדרת קובצי ה-dockerfile, וגם לספק מספיק מידע על אופן ה-build מ-makefile. - FLINT.example: במסמכים הנוכחיים לא מוסבר למה הוגדר המאגר הזה, והמטרה שלו היא לספק דוגמה לשימוש ב-FLINT. אפשר להפריד טוב יותר בין ההרצות השונות של הדוגמאות באמצעות הוראות ספציפיות להרצה שלהן. אנחנו צריכים גם לקשר את המאגר הזה למאגר הראשי שלנו ב-FLINT, כדי לספק למשתמשים דרך לנווט לכאן ולבדוק את הדוגמה בפעולה.
צריך להוסיף את המידע הבא למסמכי התיעוד הנוכחיים: - שימוש ב-Git וב-GitHub: המידע הזה יכלול הוראות מפורטות ליצירת ענף מקור, לשכפול ולאחר מכן להגדרת המקור המרוחק של המאגר. הוא גם יספק מידע על איך לבצע rebase מול המאסטר העדכני ביותר של נתונים ולטפל בהתנגשויות מיזוג. - תגים וסמלי אמוג'י: במסמכים הנוכחיים אין תגים וסמלי אמוג'י שיכולים לעזור לתורמים חדשים להרגיש רצויים ולמצוא את הבעיות בקלות רבה יותר. - מידע על הבעיות שמתאימות למשתמש חדש/למתחילים: המידע הזה יעזור להפנות את התורמים החדשים לבעיות שמתאימות למתחילים ולאתר הקהילה. - מידע על המאגר Import-me: המאגר Import-me משמש כתבנית בסיסית להתחלת העבודה עם כל מאגר של Moja Global. במסמכים הנוכחיים אין אזכור של החשיבות של אותם נושאים. צריך לעדכן אותו כך שיכלול את מאגר Import-me, וגם להוסיף את השלבים לבחירת המאגר הזה כתבנית ביצירת מאגר חדש. צריך גם להגדיר תהליך שבו מפתחים יוכלו להציע תכונות נוספות למאגר Import-me.
שלב 2: יצירת מאגר תיעוד מרכזי ועצמאי :
הכלי שישמש לפלטפורמת האירוח:
הכלים המוצעים לפלטפורמת האירוח הזו הם 'קריאת המסמך' מהסיבות הבאות:- - קיבלו דירוג גבוה בין פלטפורמות אירוח שונות. - עדכון אוטומטי כשדוחפים את השמירה - קל להגדיר אותו, ויש תמיכה זמינה בפתרון בעיות בגלל הקהילה הגדולה שמשתמשת בו - הפורמט של המסמכים הוא reStructuredText והפלט מופעל על ידי Sphinx.
כדאי לארגן את כל התוכן באופן לוגי וסדרתי:
סדר התוכן המוצע הוא:- - מבוא למסמכים למפתחים: הקטע הזה יכיל מבוא ל-Moja Global ול-FLINT. - תרומה: החלק הזה יכלול את תתי-הסעיפים "דרכים לתרומה" (מבחינת באגים בקוד/תרגום/תיעוד/ארגון אירועים וכו') וכן "קוד התנהגות". - הגדרת פיתוח: החלק הזה יכלול תתי-סעיפים "Git ו-GitHub Workflow", 'התקנת Windows', 'התקנת כלים', 'תהליך ההתקנה הבא', ונעבור על תהליך הבדיקה של המסמך הבא. - החלק הזה יעזור למפתחים לבצע בדיקה באמצעות המסמך ונעבוד על תהליך הבדיקה הבא. - הצטרפות אלינו: בקטע הזה יוצגו פורומים שונים ברשתות החברתיות, כמו ערוצי Slack, שבהם אפשר ליצור קשר עם Moja Global ולעבוד איתה.
שלב 3: הוספת תהליך עבודה למפתחים ואתר קהילה לתורמים חדשים:
מסמכי תיעוד למפתחים בנושא תהליך העבודה:
המסמכים של תהליך העבודה למפתחים יכללו את הקטעים הבאים:
- סטאק הטכנולוגיה או הארכיטקטורה שבהם נעשה שימוש והמודולים השונים בקוד: מסמכי תיעוד שמטרתם להכיר לתורמים החדשים את סטאק הטכנולוגיה שהוטמע, את הספריות והמודולים השונים של קוד המקור.
- כלי הבדיקה והכיסוי המשולבים: אנחנו משיקים שותפים חדשים לכלי צינור עיבוד הנתונים של CI/CD שמשמשים לבדיקות, ל-Coverage bots ולבדיקות איכות אוטומטיות שפועלות על הקוד שלהם. בנוסף, יש לספק להם הנחיות לגבי מי לפנות אליו אם הבדיקות נכשלות.
- בוטים שמשמשים להקלת תהליך העבודה, למשל: Zulipbot: עיצוב תבניות תוכן לבוטים שיוצגו ותיעוד שזמין כדי לאפשר למשתמשים להבין את הבוטים ואפילו לשפר את ההגדרות שלהם על ידי תרומה.
- בדיקה ידנית ושליחה של בקשת משיכה: מסמכים שיסופקו שמסבירים איך לבדוק בקשות משיכה באופן ידני לפי סטנדרטים מסוימים ולהעלות תוצאות מבחינת צילומי מסך או קובצי GIF בשליחה של בקשות משיכה.
- הנחיות לבדיקה של בקשות משיכה שתורמים צריכים לפעול לפיהן: הנחיות לתיוג צוותים מסוימים לבדיקה ולהוספת תוויות כמו 'נדרשת בדיקה' לבקשת המשיכה, כדי לאפשר למנהלי התוכן להגיב.
אתר הקהילה:
באתר הקהילה יהיו התכונות הבאות:-
- מידע על תהליך העבודה שלנו: תהליך העבודה יכלול את סדרת הפעולות שתורם חדש יכול להתחיל לבצע, למשל – דיווח על בעיה לאנשים שמשתמשים בפרויקט בפעם הראשונה, לאחר מכן יצירה של בעיה לאנשים שמשתמשים בפרויקט בפעם הראשונה עבור מישהו אחר ועזרה לאחרים על ידי מתן משוב ובדיקת בקשות המשיכה שלהם.
- רשימת הבעיות לאנשים שמשתמשים ב-GitHub בפעם הראשונה בלבד: רשימת הבעיות שמיועדת במיוחד לאנשים שמשתמשים ב-GitHub בפעם הראשונה או לתורמים חדשים.
- רשימת הבעיות הלא עדכניות: רשימת הבעיות שלא טופלו במשך זמן רב, ולכן זמינות לבחירה על ידי שותפי תוכן.
- רשימת תורמים: רשימת התורמים שתרמו עד עכשיו למאגרים של Moja Global.
- שותפים תורמים מהזמן האחרון: רשימת השותפים התורמים שתרמו לאחרונה למאגרים של Moja Global.
- קישורים להצטרפות לפורומים בצ'אט: מידע וקישורים להצטרפות לקהילת Slack כדי לפתור את השאילתות שלהם ולנהל דיונים נוספים על הפרויקטים.