בדף הזה מופיעים הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Docs ל-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.
תוצאות צפויות של פרויקט - אתר פרויקט פשוט ויעיל המשלב מסמכים, הפניות לקוד, מדריכים וחדשות. - מדריך למשתמש שעבר שינוי מבני ובדיקה, ומפריד בין תוכן המיועד למשתמשים לבין תוכן המיועד למפתחים, וגם כולל מידע שהיה חסר בעבר. - תהליך עבודה של מדריכים מתוך דוגמאות זמינות של משאבי עזרה, שאלות נפוצות ובעיות נפוצות.
כלים לפרויקט במסמכי התיעוד הנוכחיים של 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 שבועות (שלב פיתוח המסמכים)