דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- VLC
- כתב טכני:
- אבישק פרטאפ סינג
- שם הפרויקט:
- המשך תהליך המודרניזציה של תיעוד המשתמשים של VLC
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
הסטטוס הנוכחי של המסמך
התיעוד למשתמש של VLC נמצא בתהליך של עדכון ועדכון. המעבר נמצא בעיצומו של תהליך המעבר מהתיעוד הישן המבוסס על Wiki[1] אל התיעוד המודרני למשתמשים של הספינקס[2] שמתארח ב-ReadTheDocs.
קהל יעד
קהל היעד הוא גם משתמש סקרן שמעוניין לחקור את התכונות של נגן המדיה של VLC מעבר לנגן מדיה רגיל, ובמידה מסוימת הוא יכול לעזור למפתחים גם להשתמש בו כמדריך קל לשימוש. לכן אני מתכנן לכלול גם הוראות שמבוססות על GUI (יחד עם תמונות במקרים הרלוונטיים) וגם שיטות המבוססות על CLI (לצד קטעי קוד), כדי שלמשתמש הקצה תהיה חופש בחירה.
לדעתי צריך לצמצם את לשון התיעוד (במיוחד את הסעיף בנושא GUI) כדי שניתן יהיה להבין את המדריך ולהטמיע אותו בעזרת מי שיש לו חשיפה נומינלית למחשבים. מצד שני, הוא לא צריך להיות ארוך מדי או מובן (במיוחד בקטע ה-CLI) שהמתכנתים מאבדים עניין.
ניתן להשיג את האיזון הנכון על ידי ציון הדרישות המוקדמות בתחילת הדף, או שמירה על קטעים אופציונליים שהמומחים יכולים לדלג עליהם.
לצורך בניית תרגומים, קהל היעד הוא מפתחים/משתמשים של VLC בעלי הבנה טובה של אנגלית ואת השפה שאליה הם יתורגמו.
כלים
התיעוד החדש נמצא בשלבי פיתוח של Sphinx והוא מתארח ב-ReadTheDocs, ומערכת בקרת הגרסאות מוטמעת ב-GitLab. עברתי כמה ניסיון בשימוש ב-Git וב-GitHub, ועזרתי לי להבין איך להשתמש ב-GitLab, למרות שהלחנתי כמה פיצ'רים שונים שלקח זמן.
לגבי Sphinx, קראתי על כך כשאחד חובבי הקוד הפתוח ציין כמה ארגונים משתמשים בו לבניית המסמכים שלהם (עם דוגמה מרשימה של 'בלנדר', שמשתמש ב-Sphinx לבניית המדריך למשתמש [3] ותיעוד ה-API [4]).
הכרתי מעט את ReadTheDocs, כלי טוב לניהול גרסאות ולאירוח תיעוד טכני. כך הצלחתי ליצור תיעוד של VLC בלי הרבה בעיות, וידוע לי שהפורמט החדש הוא 'טקסט מובנה'.
לתרגומים, VLC משתמש ב-Babel כדי ליצור קובצי .po כדי להטמיע i18n ו-l10n. נכון לעכשיו, אני מנוסה בתהליך העבודה של Babel וכיצד ליצור קובצי .mo באמצעות Sphinx.
בכוונתי להשתמש בתקופת הקישור כדי להכיר טוב יותר את המורכבויות של הכלים שהוזכרו למעלה.
פרטים למסירה וקו זמן שבועי
כחלק מהפרויקט לשנת 2019, חלקים מההתקנה, הממשק, האודיו, הווידאו, ההפעלה וכו' (רוב הפונקציות הבסיסיות) כבר מכוסים. לכן, אני רוצה לעדכן את הקטע לגבי שימוש מתקדם במסמכי התיעוד בנושא משתמשים, ולבצע את השינויים הנחוצים בפרויקט 2020.
DELIVERABLE 1 [Week1-2]: עדכן את התיעוד של המרת הקידוד, כפי שמצוין בסעיף 7[5].
- המרת קידוד
- המרת קידוד של מספר סרטונים
- הוספת לוגו
- מיזוג סרטונים
- חילוץ אודיו וחילוץ אודיו מקובץ
- העתקת DVD
DELIVERABLE 2 [שבוע 3-4]: עדכון באמצעות VLC כפלאגין באינטרנט[6], במהלך בדיקה ב-Firefox 77 , Chrome 83 ו-Edge 83.
- בניית דפי אינטרנט באמצעות סרטונים
- הטמעת מאפיינים של תגים
- תיאור JavaScript API
DELIVERABLE 3 [Week 5]: בדיקת הפקודות של ממשק שורת הפקודה[7] ועדכון בהתאם.
- האזנות
- בחירת מודולים
- אפשרויות ספציפיות לפריט
- מסננים
שבוע 6: שבוע אחסון זמני לשלושת התוצרים שלמעלה.
DELIVERABLE 4 [שבוע 7-8]: הכנה לתרגומים. מלבד העדכון, אני אכין תרגומים לשפות אחרות. זה חשוב כי אחרי התרגום, משתמשים ללא רקע באנגלית יוכלו לקרוא את התיעוד (ובנוסף, VLC יהיה צעד נוסף לקראת השגת שליטה בעולם [8]).
כפי שצוין בקטע 'כלים' בהצעה, VLC משתמש כרגע ב-Babel ליצירת קובצי .po לתרגומים. אני אתעד את התהליך למשתמש/מתנדב/ת כדי:
- להוריד ולבנות את התיעוד הבסיסי באופן מקומי.
- השתמש ב-Babel כדי ליצור את הקבצים הדרושים.
- מזינים תרגומים למחרוזות.
- בניית התיעוד המתורגם באמצעות Sphinx.
- מבצעים את השינויים.
DELIVERABLE 5 [שבוע 9-10]: התכונן לתיעוד המודולים. כפי שסיכמנו עם המנטורים, אני מתכנן להכין תיעוד של המודולים בשני חלקים.
חלק - א': יצירת קבצים ליד המודולים באמצעות סקריפט שמחפש אפשרויות חוקיות מבסיס הקוד ומחלץ את השימוש בהן בשורה אחת (וערכי ברירת מחדל) מדפי ה-wiki המתאימים. זה ישמש כטיוטה בסיסית.
חלק – ב': בניית מבנה ספציפי לפלטפורמה שמקשר את כל המודולים+יישומי הפלאגין+אפשרויות לפלטפורמה מסוימת (Windows, אם יש זמן, גם עבור Fedora).
יצירת קבצים ליד המודולים תבטיח שהתיעוד קרוב לקוד המקור. גישה מלמטה למעלה, תיעוד המודולים הראשי ייבנה משילוב הקבצים שנוצרו בחלק - I ושימוש במבנה בחלק - II כחומר עזר.
צריך לבדוק את הקבצים שנוצרו באופן אוטומטי, אבל העדיפות הראשונה היא ליצור מסגרת פונקציונליות. אחרי שאסיים את התהליך, ולפי הזמן שזמין, אבדוק את הקבצים כדי לאמת את האפשרויות. המסגרת מקבלת עדיפות מאחר שהיא זמינה, המפתחים והתחזוקה יכולים גם להתחיל לתרום על ידי הוספת תרחישים רלוונטיים לדוגמה.
בונוס ניתן לשחרור [שבוע 11]: כדאי להתכונן לגרסה 4.0. למקרה שהפרויקט יישאר עומד בלוח הזמנים, אני רוצה להציע בונוס שניתן להעברה. כפי שסיכמנו עם המנטורים, כדי להתכונן לגרסה 4.0 צריך שיהיה תיעוד יציב וכמעט מלא לגרסה 3.0.
לכן, אעבור על המסמכים שכבר הושלמו לגבי הקטעים הבאים כדי לאמת ולעדכן את השיטות שצוינו:
- שימוש בסיסי: מדיה, הפעלה, אודיו, וידאו, כתוביות, מקשי קיצור, הקלטות, הגדרות, טיפים וטריקים.
- שימוש מתקדם: נגן, ממשק, המרת קידוד, סטרימינג, מקרים חריגים.
- תוספים: תוספים, סקינים.
שבוע 12: שבוע אחסון זמני לשלושת התוצרים שלמעלה + דוחות סופיים.
למה אני האדם המתאים לביצוע הפרויקט הזה?
כחובב טכנולוגיה יש לי ניסיון בשימוש בתוכנות או בבדיקה שלהן, ולפעמים אני מנסה להבין את העקרונות הבסיסיים של הקוד שלהן. למעשה, כשניסיתי להבין את בסיס הקוד של ארגון קוד פתוח, זו הפעם הראשונה שהבנתי באמת את חשיבות התיעוד. בנוסף, כחובב מוזיקה, יש לי הרבה ניסיון בביצוע שינויים קטנים ב-VLC :)
חוץ מזה, כל חיי הייתי חוקרת וסופרת. אני אף פעם לא יכולה להבין משהו, אלא אם אני כותבת דברים, וההרגלים האלה הפכו אותי לכותבת הערות ולתעדכנות באופן יעיל.
החפיפה בין שני ההרגלים האלה היא הדבר שהכי מתאים לי לתיעוד טכני. אני יכולה להתמצא בהיבטים הטכניים וגם לתעד את הממצאים/התהליכים שלי באופן שהמשתמשים מבינים.
Links: [1] https://wiki.videolan.org/מצו