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