בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- The Linux Foundation
- כותב טכני:
- boron
- שם הפרויקט:
- שיפור האירוח והיצירה של מסמכי התיעוד, וארגון מחדש של הדפים למתחילים ומדריכי המפתחים.
- משך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
תקציר :
תיעוד נועד לעזור למשתמשי קצה ולמפתחים להשתמש במוצר או בשירות. תיעוד טוב הוא חשוב מאוד כי הוא מאפשר למשתמשים ללמוד איך להשתמש בתוכנה, בתכונות שלה, לקבל טיפים וטריקים וגם לפתור בעיות נפוצות שנתקלים בהן כשמשתמשים בתוכנה. בנוסף, התיעוד מפחית את עלויות התמיכה ומהווה חלק מהזהות התאגידית ומהזהות של קוד פתוח של המוצר : תיעוד טוב הוא סימן לבריאות המוצר ולצוות המפתחים.
בלי תיעוד טוב, יכול להיות שמשתמש לא יידע איך לבצע את הפעולות שלמעלה בצורה יעילה. מסמכי תיעוד יכולים למלא תפקיד מרכזי בהבטחת ההצלחה של מוצר, כי תקשורת טובה היא תמיד הבסיס לכל עסק או מוצר, ותיעוד טוב פשוט לוקח את התקשורת הזו ומציב אותה במסגרת ניהולית שכולם יכולים לגשת אליה כדי להצליח.
כל אתר תיעוד צריך צינור עבודה טוב לבנייה ולאירוח. בארגון כמו AGL, עם כמה גרסאות והרבה תיעוד מפורט, קובצי התיעוד (markdown) מפוזרים על פני כמה מאגרי מידע, מה שהופך את המשימה של תחזוקה ועדכון שלהם למורכבת מאוד ולוקחת הרבה זמן.
המצב הנוכחי :
- אתר התיעוד של AGL מבוסס על אוסף של קובצי Markdown שנשלפו ממאגרים שונים.
- דפי המסמכים מתארחים כרגע במקורות הנפרדים בפורמט Markdown באמצעות המנוע של פרויקט Cordova.
- התוצאה היא הגדרה של ארבעה מאגרי מידע לתהליך של בניית התיעוד ואירוח שלו :
- 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-grade-linux/docs-sources] : מקור (markdowns [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) למסמכים כלליים, מדריכים.
- Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : מאגר של דפי GitHub שנפרסו באתר התיעוד [https://gist.github.com/growupboron/docs.automotivelinux.org].
- כלי (סקריפט) שזמין ב-docs-tools [https://github.com/automotive-grade-linux/docs-tools] אוסף את כל קובצי ה-Markdown ויוצר מהם תבניות בהתאם ל-fetched_files.yml שנמצא ב-docs-webtemplate [https://github.com/automotive-grade-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-grade-linux/docs-gh-pages], שמוטמע בהתאם.
- התהליך הנוכחי של תחזוקת צינור הנתונים לא ידידותי למשתמשים ולמפתחים, במיוחד למשתתפים חדשים. אפשר לפשט ולייעל את תהליך העבודה הזה (של בנייה ואירוח) כדי שהמפתחים יוכלו להתמקד בחלק של התיעוד ולא בתחזוקה של תהליך העבודה של יצירת התיעוד והפריסה שלו.