דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- CERN-HSF
- כתב טכני:
- SabitaR
- שם הפרויקט:
- בנייה מחדש וייעול של מסמכי התיעוד של Allpix Squared
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
סקירה כללית בחרתי בפרויקט Allpix Squared של CERN-HSF משתי סיבות עיקריות:
רכישת מיומנות: התיעוד הקיים של הפרויקט הזה מקיף ומשלב פורמטים שונים של תוכן. ביקורת וארגון מחדש של חבילת המסמכים המקיפה הזו יעזרו לי לשפר את ארכיטקטורת המידע ואת מיומנויות הכתיבה שלי. בנוסף, דומיין הפרויקט (פיזיקה של חלקיקים!) חדש לי. התוכנית מאתגרת אותי לשפר את מיומנויות האינטראקציה שלי עם מפתחים. אני מאמין/ה שכותבים טכניים יכולים לעבד מידע ממפתחים ולהציג תוכן שימושי לכל רמה של משתמשים, אם אנחנו מבצעים את מחקר הרקע הדרוש שלנו ושואלים את השאלות הנכונות. הפרויקט הזה יאפשר לי לבחון את התיאוריה הזו!
ידע טכני: לפרויקט הזה נדרש Hugo – כלי שמופיע בראש רשימת הלמידה שלי. אשמח ללמוד את תהליך העבודה של LaTeX-Markdown-Hugo-GitLab-CI.
במהלך השלב של ניתוח הכותבים הטכניים, שוחחתי בקצרה על המנטורים של הפרויקט והכרתי את המבנה הקיים של חבילת המסמכים. בנוסף, בניתי אתר להדגמה (https://ap2-demo.netlify.app/) כדי לבדוק אם אני יכול להגדיר כראוי את Hugo ו-Docsy במחשב Windows שלי. הצלחתי לפרוס את האתר ב-Netlify, אבל לא ב-Gitlab Pages. כדי שהפרויקט הזה ישמור על תהליך הפריסה הנוכחי שלו, אני אמצא דרך לפרוס את העיצוב Hugo Docsy בדפי Gitlab.
תוצאות הפרויקט של OLD - אתר פרויקטים יעיל שמשלב מסמכים, הפניות לקוד, מדריכים וחדשות. - מדריך משתמש מאורגן ונבדק, שמפריד בין תכנים המיועדים למשתמשים ולמפתחים וכולל מידע שחסר בעבר. - תהליך עבודה של מדריכים מתוך דוגמאות זמינות של תיעוד, שאלות נפוצות ובעיות נפוצות.
כלים לפרויקטים במסמכי התיעוד הנוכחיים של Allpix Squared נעשה שימוש ב-LaTeX, ב-Doxygen, ב-pandoc וב-Hugo, בנוסף ל-GitLab ול-Gitlab CI. המנטורים של הפרויקט ואני שוחחתי בצ'אט על האפשרות להעביר תוכן מ-LaTeX ל-Markdown באמצעות יישומי פלאגין של MathJax. אם אצליח, תהליך העבודה של המסמך יכלול את Hugo, Markdown, Doxygen, git ו-Gitlab CI. כדי שהמדריכים יישארו באותו אתר או באותה פלטפורמה, אשתמש ב-Hugo וב-Markdown. מעניינת אותי האפשרות להשתמש ב-Codelabs-as-a-Tool (ClaaT) למדריכים. ביולי, אני מקווה לבדוק את תהליך העבודה של ClaaT-Hugo ולדון עליו עם המנטורים, אם ייבחרו.
משך הפרויקט אני מבקש לסיים את הפרויקט Allpix Squared במהלך התקופה הסטנדרטית של שלושה חודשים (14 בספטמבר 2020 עד 30 בנובמבר 2020), שבמהלכה אקדיש כ-15 שעות בשבוע להשקעה. השעות האלה יכללו פגישות של מנטורים ואימיילים קשורים, לפי הצורך. אפעל בהתאם ללוחות הזמנים של GSoD ליצירת קשרים קהילתיים ולסיום פרויקטים גם כן.
משימות לפרויקטים כך אני מתכוון ליישם את העדכונים שלי בחבילת המסמכים הקיימת של Allpix Squared: 1. לערוך מחקר, לדון באפשרויות ולעיין בהן (17 באוגוסט עד 13 בספטמבר 2020): - להבין את דרישות הפרויקט - להתקין את התוכנה Allpix Squared כדי לזהות מידע חסר במסמכים הנוכחיים, אם יש כזה. - מבקשים את פרטי הכניסה הנדרשים. - יצירת תהליכי עבודה למשתמשים שונים ב-Allpix Squared - סיווג תוכן לפי תפקיד המשתמש - בדיקת ההשלכות של המרת קובצי LaTeX ל-Markdown - איחוד מאגרי מקור או הבנה של אופן העבודה עם מספר מאגרי Git - בונוס: בדיקת CLaaT כאפשרות למדריכים/מדריך קצר בנוגע לציר הזמן כדי לעזור ביצירת מדריכים ליצירת מסמכים מקוצרים לקהילה:
שינוי המבנה, בדיקה ושיפור של התוכן (14 בספטמבר עד 19 באוקטובר 2020): שתי משימות בשבוע, בין 5 ל-7 שעות לכל משימה. ציר הזמן הזה כולל שבוע הפסקה לצורך טיפול בעיכובים או בבעיות בלתי צפויים.
- בדיקת הסיווגים הקיימים של תוכן ומשתמשים, תוך התחשבות בתהליכי העבודה של המשתמשים
- מתאר ובודקים את תהליך העבודה של תוכן מובנה עבור משתמשים שונים
- מקור ושיפור של תוכן חסר
- המרת קובצי LaTeX ל-Markdown
- השלמת התוכן של המדריך למשתמש ושל המדריך למפתחים
- יצירת קובצי PDF של המדריכים למשתמש ולמפתחים
- בונוס: בניית תוכן של מדריכים מדוגמאות ובעיות
- בונוס: הגדרת תהליך עבודה של מדריך לדוגמאות של הנחיות ציר זמן: 5 שבועות (שלב פיתוח המסמך)
בניית האתר (19 באוקטובר עד 30 בנובמבר 2020): 1-2 משימות בשבוע, 5-7 שעות לכל משימה. ציר הזמן הזה כולל שבוע של אחסון זמני לצורך פתרון בעיות ושיפור הפלט הסופי.
- הסבר על תהליך הפרסום ובדיקה שלו
- בניית מבנה אתר באמצעות Hugo ו-Docsy
- בדיקה של השמירה על הפריסה האוטומטית ועל תהליך העבודה הנוכחי באמצעות Docsy
- הוצאת תוכן מ-Doxygen
- פיתוח מדריכים למשתמש, מדריך למפתחים ומדריכים מהתוכן של LaTex או Markdown
- השלמת העיצוב של אתר הפרויקט (לוגו, צבעים, תבנית, פריסה, קישורים, נוחות השימוש ו-Gitlab CI/CD) ציר הזמן: 6 שבועות (שלב פיתוח המסמך)