בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- The Linux Foundation
- כותבים טכניים:
- בורון
- שם הפרויקט:
- שינוי אופן האירוח והיצירה של מסמכי התיעוד, ושינוי המבנה של דפי תחילת העבודה ומדריכים למפתחים.
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
תקציר :
מסמכי תיעוד נועדו לעזור למשתמשי קצה ולמפתחים להשתמש במוצר או בשירות. תיעוד טוב הוא חשוב מאוד כי הוא מספק למשתמשים דרך ללמוד איך להשתמש בתוכנה, להכיר את התכונות שלה, לקבל טיפים וטריקים וגם לפתור בעיות נפוצות שנתקלים בהן בזמן השימוש בתוכנה. בנוסף, הוא מפחית את עלויות התמיכה והוא חלק מהזהות הארגונית והזהות של המוצר כקוד פתוח : תיעוד טוב הוא סימן לבריאות המוצר ולצוות המפתחים.
ללא תיעוד טוב, יכול להיות שמשתמש לא ידע איך לבצע את הפעולות שלמעלה בצורה יעילה ויעילה. מסמכי תיעוד יכולים למלא תפקיד מרכזי בהבטחת ההצלחה של מוצר, כי תקשורת טובה תמיד תהיה בלב ליבה של כל עסק או מוצר, ומסמכי תיעוד טובים פשוט מעבירים את התקשורת הזו למסגרת ניהולית שכל אחד יכול לגשת אליה כדי להצליח.
לכל אתר מסמכי עזר צריך צינור עיבוד נתונים טוב ליצירה ולאירוח של תהליך העבודה. בארגון כמו AGL, עם כמה גרסאות והרבה מסמכי עזר מפורטים, קובצי המסמכים (markdowns) מפוזרים במספר מאגרים, ולכן המשימה של התחזוקה והעדכון שלהם מורכבת מאוד ותובעת הרבה זמן.
המצב הנוכחי :
- אתר המסמכים של AGL מבוסס על אוסף של קובצי markdown שאוחזרו ממאגרים שונים.
- דפי המסמך מתארחים כרגע במקורות המידע הספציפיים כ-Markdown באמצעות המנוע של פרויקט cordova.
- התוצאה היא ארבע הגדרת מאגר עבור תהליך ה-build והאירוח של מסמכי התיעוד :
- Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : מכילה את תבנית האתר של Jekyll.
- Docs-tools [https://github.com/automotive-grade-linux/docs-tools] : מכיל כלים ליצירה אוטומטית של אתר טכני מקובצי Markdown.
- Docs-sources [https://github.com/automotive-grad-linux/docs-sources] : מקור (markdowns [https://github.com/automotive-grad-linux/docs-sources/tree/master/docs]) למסמכים כלליים, מדריכים.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : מאגר GitHub pages לפריסה של אתר המסמכים [https://gist.github.com/growupboron/docs.automotivelinux.org].
- כלי (script) שזמין ב-docs-tools [https://github.com/automotive-grad-linux/docs-tools] מטפל באיסוף ובעיבוד של כל קובצי ה-Markdown בהתאם ל-fetched_files.yml שנמצא ב-docs-webtemplate [https://github.com/automotive-grad-linux/docs-webtemplate].
- תהליך העבודה הנוכחי ליצירת אתר התיעוד של agl : current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
- הקובץ section_version.yml מכיל את הקישורים לכל קובצי ה-YAML של הספר, והוא ממשיך לאחזר את כל קובצי ה-YAML של הספר מהמאגרים המרוחקים אל docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate]. קובצי ה-yaml של הספר מכילים את כל כתובות ה-URL של קובצי ה-markdown מהמאגר המרוחק.
- מיד אחרי שכל קובצי ה-markdown מאוחזרים, תהליך הכלים ליצירת אתר המסמך של AGL ב-docs-gh-pages [https://github.com/automotive-grad-linux/docs-gh-pages] שנפרס בהתאמה.
- התהליך הנוכחי של ניהול צינור עיבוד הנתונים לא ידידותי למשתמשים ולמפתחים, במיוחד לתורמים חדשים. אפשר לפשט ולייעל את צינור עיבוד הנתונים של תהליך העבודה (של ה-build והאירוח) כדי למקד את המפתחים בחלק של התיעוד, במקום לשמור על תהליך העבודה של יצירת התיעוד ופריסתו.