בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- VLC
- כותבים טכניים:
- אבישק פראטאפ סינג
- שם הפרויקט:
- המשך המודרניזציה של מסמכי התיעוד למשתמשי VLC
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
הסטטוס הנוכחי של התיעוד
אנחנו מעדכנים ומחדשים את מסמכי התיעוד למשתמשי VLC. אנחנו בתהליך מעבר מהמסמכי העזרה הקודמים שמבוססים על ויקיפדיה[1] למסמכי העזרה המודרניים של המשתמשים שנוצרו באמצעות Sphinx[2] ומתארחים ב-ReadTheDocs.
קהל היעד
קהל היעד הוא גם משתמשים סקרנים שרוצים לחקור את התכונות של נגן המדיה VLC מעבר לנגן מדיה רגיל, ובמידה מסוימת, הוא יעזור גם למפתחים על ידי הצגת מדריך עזר פשוט. לכן, אני מתכנן לכלול גם הוראות מבוססות-GUI (יחד עם תמונות במקרים הרלוונטיים) וגם שיטות מבוססות-CLI (יחד עם קטעי קוד), כדי שמשתמש הקצה יוכל לבחור מה מתאים לו.
לדעתי, השפה של המסמכים (במיוחד הקטע בנושא ממשק משתמש גרפי) צריכה להיות פשוטה מספיק כדי שאדם עם חשיפה מינימלית לשימוש במחשבים יוכל להבין את המדריך ולהטמיע אותו. מצד שני, הוא לא צריך להיות ארוך מדי או להסביר יותר מדי (במיוחד הקטע של CLI), כדי שהמפתחים לא יאבדו עניין.
אפשר להשיג את האיזון הנכון על ידי ציון דרישות מוקדמות בתחילת הדף, או על ידי שמירת קטעים אופציונליים, שמשתמשים מנוסים יכולים לדלג עליהם.
כשמפתחים תרגומים, קהל היעד הוא מפתחים או משתמשים של VLC שיש להם הבנה טובה של אנגלית ושל השפה שאליה הם מתרגמים.
כלים
המסמכים החדשים נוצרים באמצעות Sphinx ומתארחים ב-ReadTheDocs, ומערכת בקרת הגרסאות מיושמת ב-GitLab. יש לי ניסיון קודם בשימוש ב-Git וב-GitHub, שעזר לי להבין את GitLab, אבל היו תכונות מסוימות שדרשו זמן מה כדי ללמוד אותן.
ובנוגע לספינקס, קראתי על זה כשחובב אחר של קוד פתוח אמר כמה ארגונים משתמשים בו ליצירת התיעוד שלהם (עם הדוגמה הידועה של Blender, שמשתמשת ב-Sphinx ליצירת המדריך למשתמש[3] ומסמכי ה-API[4]).
הכרתי קצת את ReadTheDocs, כלי טוב לניהול גרסאות ולאירוח מסמכי עזרה טכניים. לכן הצלחתי ליצור את המסמכים של VLC בלי בעיות רבות, ואני מכיר את הפורמט reStructured Text שבו נעשה שימוש.
לצורך תרגומים, VLC משתמש ב-Babel כדי ליצור קובצי .po כדי להטמיע i18n ו-l10n. כרגע אני לומד את תהליך העבודה של Babel ואת האופן שבו יוצרים קובצי .mo באמצעות Sphinx.
אני מתכוון להשתמש בתקופה הזו כדי להכיר לעומק את המורכבות של הכלים שצוינו למעלה.
העברות וציר הזמן השבועי
כחלק מהפרויקט של 2019, כבר יש כיסוי לחלקים של התקנה, ממשק, אודיו, וידאו, הפעלה וכו' (רוב הפונקציות הבסיסיות). לכן, בפרויקט של 2020, אני רוצה לעדכן ולעבוד על הקטע 'שימוש מתקדם' במסמכי התיעוד למשתמש.
פריט מס' 1 [שבוע 1-2]: עדכון המסמך בנושא המרת קוד, כפי שצוין ב-#7[5].
- המרת קידוד
- המרת קידוד של כמה סרטונים
- הוספת לוגו
- מיזוג סרטונים ביחד
- חילוץ אודיו וחילוץ אודיו מקובץ
- איך מעתיקים DVD
פריט הגשה 2 [שבוע 3-4]: עדכון של השימוש ב-VLC כפלאגין אינטרנט[6], תוך בדיקה ב-Firefox 77, ב-Chrome 83 וב-Edge 83.
- יצירת דפי אינטרנט עם סרטונים
- הטמעת מאפייני תגים
- תיאור של JavaScript API
מטלה 3 [שבוע 5]: בודקים את הפקודות של ממשק שורת הפקודה[7] ומעדכנים בהתאם.
- האזנות
- בחירת מודולים
- אפשרויות ספציפיות לפריט
- מסננים
שבוע 6: שבוע חלון לשלוש התוצרים שצוינו למעלה.
DELIVERABLE 4 [שבוע 7-8]: הכנות לקראת התרגומים. בנוסף לעדכון, אעשה הכנה לתרגומים לשפות אחרות. זה חשוב, כי אחרי התרגום, משתמשים ללא רקע באנגלית יוכלו לקרוא את התיעוד (ובנוסף, חשוב לציין, VLC הוא צעד נוסף לקראת השגת השליטה בעולם [8]).
כפי שצוין בקטע 'כלים' בהצעה, VLC משתמש כרגע ב-Babel כדי ליצור קובצי .po עבור תרגומים. אני אתעד את התהליך בשביל משתמש או מתנדב:
- להוריד ולפתח את התיעוד הבסיסי באופן מקומי.
- משתמשים ב-Babel כדי ליצור את הקבצים הנדרשים.
- צריך להזין תרגומים למחרוזות.
- יצירת מסמכי התיעוד המתורגמים באמצעות Sphinx.
- שומרים את השינויים.
מטלה 5 [שבוע 9-10]: הכנה למסמכי התיעוד של המודולים. כפי שסיכמתי עם המנטורים, אני מתכנן להכין את המסמכים של המודולים בשני חלקים.
חלק ראשון: יצירת קבצים ליד המודולים באמצעות סקריפט שמחפש אפשרויות תקינות ממסד הקוד ומחלץ את אופן השימוש שלהן בשורה אחת (ואת ערכי ברירת המחדל) מדפי הוויקי המתאימים. המסמך הזה ישמש כטיוטה בסיסית.
חלק II: בניית מבנה ספציפי לפלטפורמה שמקשר את כל המודולים, התוספים והאפשרויות לפלטפורמה מסוימת (Windows, ואם הזמן יאפשר, גם ל-Fedora).
יצירת קבצים ליד המודולים תבטיח שהתיעוד קרוב לקוד המקור. באמצעות גישה מלמטה למעלה, מסמכי העזרה הראשיים של המודולים ייוצרו על ידי שילוב של הקבצים שנוצרו בחלק הראשון, תוך שימוש במבנה שנוצר בחלק השני כמקור עזר.
הקבצים שנוצרים באמצעות אוטומציה צריכים לעבור בדיקה, אבל העדיפות הראשונה היא ליצור מסגרת פונקציונלית. ברגע שהיא תושג, ובהתאם למועד הזמין, אבדוק את הקבצים כדי לאמת את האפשרויות. המסגרת מקבלת עדיפות ברגע שהיא זמינה, וגם המפתחים והמתחזקים יכולים להתחיל להוסיף תוכן על ידי הוספת תרחישים לדוגמה רלוונטיים.
BONUS DELIVERABLE [שבוע 11]: מתכוננים לגרסה 4.0. אם הפרויקט יתבצע לפי לוח הזמנים, אשמח להציע לך פריט בונוס. כפי שסוכם עם המנטורים, ההכנה לקראת השקת הגרסה 4.0 מחייבת שתהיה לכם תיעוד יציב וכמעט מלא לגרסה 3.0.
לכן, עליי לעבור על המסמכים שכבר מילאת לגבי הסעיפים הבאים כדי לאמת ולעדכן את השיטות שצוינו:
- שימוש בסיסי: מדיה, הפעלה, אודיו, וידאו, כתוביות, מקשי קיצור, הקלטות, הגדרות, טיפים וטריקים.
- שימוש מתקדם: נגן, ממשק, המרה, סטרימינג, מקרים חריגים.
- תוספים: תוספים, סקינים.
שבוע 12: שבוע חלון לשלוש התוצרים שצוינו למעלה + דוחות סופיים.
למה אני מתאים לפרויקט הזה?
בתור חובב טכנולוגיה, יש לי ניסיון בשימוש בתוכנות ובבדיקתן, ולפעמים גם בניסיון להבין את בסיס הקוד שלהן. למעשה, הניסיון להבין את בסיס הקוד של ארגון בקוד פתוח הייתה הפעם הראשונה שהבנתי באמת את חשיבות התיעוד. יתרה על כך, כחובבי מוזיקה יש לי הרבה ניסיון בניהול עם VLC :)
מלבד זאת, הייתי חוקרת וכותבת כל חיי. אם לא כותבים משהו, אף פעם לא מבינים אותו באמת. ההרגל הזה הפך אותי לאדם שמצליח לכתוב הערות ולתעד בצורה יעילה.
השילוב של שתי ההרגלים האלה הוא מה שמתאים אותי לכתיבה של מסמכי עזרה טכניים. אני יכול למצוא את הדרך שלי בתוך ההיבטים הטכניים, תוך תיעוד הממצאים או התהליכים שלי בצורה שהמשתמשים יוכלו להבין.
קישורים: [1] https://wiki.videolan.org/Documentation:User_Guide/ [2] https://vlc-user-documentation.readthedocs.io/en/latest/index.html [3] https://docs.blender.org/manual/en/latest/ [4] https://docs.blender.org/api/current/index.html [5] https://code.videolan.org/docs/vlc-user/-/issues/7 [6] https://wiki.videolan.org/Documentation:WebPlugin/ [7] https://wiki.videolan.org/Documentation:Command_line/ [8] https://trac.videolan.org/vlc/ticket/35