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