פרויקט VideoLAN

דף זה מכיל את הפרטים של פרויקט כתיבה טכני שהתקבל בעונת Google Docs.

סיכום הפרויקט

ארגון הקוד הפתוח:

VideoLAN

כתב טכני:

אדיונג אני אסיפו

שם הפרויקט:

מודרני (שכתוב) של מסמכי התיעוד למשתמשים של VLC

אורך הפרויקט:

אורך רגיל (3 חודשים)

תיאור הפרויקט

מופשט

מסמכי תיעוד למשתמשים נועדו לעזור למשתמשי קצה להשתמש במוצר או בשירות. תיעוד טוב למשתמשים חשוב מאוד, כי הוא מספק למשתמשים אפשרות ללמוד כיצד להשתמש בתוכנה, בתכונות, בטיפים ובטריקים שלה, וגם לפתור בעיות נפוצות שבהן הם נתקלים בעת השימוש בתוכנה. הוא גם מפחית את עלויות התמיכה והוא חלק מהזהות הארגונית של המוצר: תיעוד טוב של המשתמש הוא סימן לתקינות המוצר – צוות המפתחים.

ללא תיעוד טוב, יכול להיות שהמשתמש לא יידע איך לבצע את הפעולות שמפורטות למעלה בצורה יעילה ואפקטיבית. לתיעוד משתמשים יש תפקיד מרכזי בהבטחת הצלחה של מוצר, כי תקשורת מעולה היא העיקרון המנחה של כל עסק או מוצר. תיעוד נהדר רק לוקח את התקשורת הזו ומציב אותה במסגרת ניתנת לניהול שאליה כולם יכולים לגשת כדי להצליח.

נכון לרגע כתיבת הנתונים האלה, התבצעה גישה לתיעוד המשתמשים של VLC 4,634,065 פעמים ומתבצעת הורדה של נגן המדיה של VLC כ-23 מיליון פעמים בחודש מהאתר הראשי. זה מראה שהרבה אנשים ברחבי העולם משתמשים ב-VLC Media Player ומומלץ לקרוא את התיעוד של המשתמש שלו כדי לקבל הנחיות לגבי אופן השימוש בנגן המדיה. עם זאת, תיעוד המשתמשים של נגן המדיה של VLC אינו מעודכן כרגע וחלקי (הוא עודכן לאחרונה ב-28 באוקטובר 2015), וקהילת VideoLAN מעוניינת להשתמש בפרויקט הזה כדי לשפר את תיעוד המשתמשים שלה כדי לאפשר למשתמשי קצה ליהנות מחוויה חלקה כשהם משתמשים בנגן המדיה VLC.

מצב נוכחי

נכון לעכשיו, תיעוד המשתמשים זמין בדף wiki. הוא מיושן, חלקי, קשה לניווט או למצוא מידע, לא כולל מידע על הגרסה הנוכחית של נגן המדיה, ואפשר לתרגם אותו רק בגרמנית, וזה גורם לתקלה חמורה בקרב אנשים שלא יודעים לקרוא את השפה האנגלית.

למה המסמך המוצע שלי של המשתמש הוא שיפור על פני המסמך הנוכחי?

מסמכי התיעוד למשתמשים ייבנו במטרה לשפר את המדיניות ולוודא שהיא יעילה, עקבית ושקטת הנפש של משתמשי הקצה. התוכן יכלול מדריכים כתובים ואת התמונות המשויכות אליו, וכן הוראות והסבר על השימוש בכל תכונה של נגן המדיה VLC. הוא יהיה עדכני, קל לניווט, מובן וניתן לתרגום בחמש שפות עיקריות לפחות.

מנטורים: ז'אן-בטיסט, אלכס, סיימון

ניתוח

שוחחנו עם ז'אן-בפטיסט ודיברתי על הסביבה החדשה שאליה יועברו מסמכי התיעוד של המשתמשים הנוכחיים לצורך שיפורים. הוא שיתף שני קישורים שהראו מאגר של Gitlab של קובץ המקור שנכתב עם Sphinx ואת התיעוד העיקרי שמתארח ב-Read the Docs. הוא אמר שהם מצפים שהמסמכים החדשים יהיו דומים להם. חקרתי הרבה על הכלים האלה כדי להבין טוב יותר איך הם פועלים.

ספינקס

Sphinx הוא פתרון עמיד ובוגר לתיעוד תוכנה. המהדורה כוללת כמה תכונות שהכותבים מצפים להן, כמו פרסום מקור יחיד, שימוש חוזר בתוכן באמצעות הכללה, כולל, בהתאם לסוג התוכן ולתגים, מספר עיצובי HTML למבוגרים שמספקים חוויית משתמש מעולה בנייד ובמחשב, התייחסות לדפים, למסמכים ולפרויקטים תמיכה באינדקס ומילון מונחים ותמיכה בלוקליזציה. הוא משתמש גם ב-reStructuredText כשפת הסימון, ורבות מיתרונותיו מגיעים מהעוצמה והפשטות של reStructuredText והיכולת לתרגם תיעוד.

לקריאת המסמכים ב-Docs

קרא את מסמכי Docs כדי לפשט את מסמכי התיעוד של התוכנה על ידי הפיכת הבנייה, ניהול הגרסאות והאירוח של המסמכים שלך לאוטומטיים עבורך. זה אף פעם לא יוצא להסתנכרן. כלומר, בכל פעם שדוחפים קוד למערכת בקרת הגרסאות המועדפת עליכם, בין אם זו Git , Mercurial , Bazaar או Subversion, Read the Docs יבנה את המסמכים שלכם באופן אוטומטי כך שהקוד והתיעוד שלכם יהיו תמיד מעודכנים. יש לה מספר גרסאות. קרא את Docs יכול לארח ולבנות גרסאות מרובות של המסמכים שלך, כך שגרסת 1.0 של המסמכים וגרסת 2.0 של המסמכים שלך קלה כמו הסתעפות או תג נפרדים במערכת בקרת הגרסאות שלך. 'Docs' הוא כלי חינמי וקוד פתוח שמארח תיעוד של כמעט 100,000 פרויקטים גדולים וקטנים של קוד פתוח, כמעט בכל שפת אדם ומחשב.

אימות

'Sphinx' הוא כלי חזק במיוחד, ו-Read the Docs מתבסס על העיצוב העליון כדי לספק אירוח של מסמכי Sphinx ששומר על המסמכים שלכם מעודכנים בכל הגרסאות. ביחד, מדובר בקבוצה נהדרת של כלים שמפתחים וכותבים טכניים יכולים להיעזר בהם כדי ליצור מסמכי תיעוד למשתמשים, שהכי מתאימים למשתמשי הקצה.

'Sphinx' כולל תמיכה בתרגום תיעוד למספר שפות. יש תמיכה במערכת לניהול גרסאות שתשמש לניהול התיעוד. בניגוד ל-wiki הנוכחי, שבו כל אחד יכול לערוך ולא להוסיף את המידע הנכון, המערכת הזו לניהול גרסאות תוודא שכל השינויים ייבדקו ראשונים לפני שהם ימוזגו למאגר הראשי. כמו כן, ניהול הגרסאות יאפשר לתיעוד להגדיל את התרומה של קוד פתוח לפרויקט, מפני שאנשים יכולים ליצור בעיות, בקשות משיכה פתוחות וכו'. Sphinx וקוראים את ה-Docs משמשים רשימה של קהילות נהדרות אחרות כמו ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs וכו'. זהו כלי נהדר לשימוש במסמכי התיעוד החדשים למשתמשים ב-VLC.

לא רק קראתי על הכלים האלה, וגם יצרתי דוגמה בסיסית. זה הקישור: https://gitlab.com/Didicodes/demo-vlc-user-documentation למאגר Gitlab שלי, ואילו את הגרסה המתארחת ב-Readthedocs אפשר למצוא כאן: [https://vlc-user-document-demo.readthedocs.io/en/updated/](https://vlc-user-document-demo.readthedocs.io/en/updated/.

מבנה המסמך המוצע

יצרתי מבנה עבור התיעוד למשתמשים של VLC, שניתן למצוא כאן: https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. לפני התחלת היישום של המבנה החדש, הוא צריך לקבל אישור מהחונכים. המשמעות היא שהמבנה ככל הנראה ישתנה לאחר שייבדק על ידי החונכים.

יעדי הפרויקט

• שינוי המבנה של המסמכים.
• מעדכנים את התיעוד כך שיתאים לגרסאות המודרניות של VLC.
• העברת תיעוד המשתמשים ל-Gitlab באמצעות Sphinx ו-ReadtheDocs.
• יש להסיר תמונות ומידע ישנים.
• לשכתב את תיעוד המשתמש כדי שיהיה קל יותר להבין אותו.
• להגדיר לתרגום באמצעות לוקליזציה של Sphinx.
• יוצרים מעורבות של קהילת התיעוד כדי שהמשתמשים יוכלו לדווח או לפתור בעיות שהם נתקלים בהן בזמן קריאת התיעוד.

למה כדאי לפרויקט הזה?

תמיד הייתה לי אמון בכתיבת קוד, בפתרון בעיות ובבניית תוכנה, כאשר יש לכם את היכולת להעשיר את הידע של המשתמשים על כך באמצעות כתיבה. באופן אישי, תמיד נרתקתי מהמאמצים של קהילת VideoLAN ליצירת פתרונות תוכנה חינמיים למולטימדיה. בילדותי, נגן המדיה של VLC תמיד היה התוכנה שבה השתמשתי כשהאזנתי למוזיקה או כשצפיתי בסרט, כי הוא היה חזק מאוד והכיל כל כך הרבה תכונות. זה יהיה כבוד לעבוד עם הקהילה שתרמה להפוך את ילדותי למדהימה.

למה אני האדם המתאים לפרויקט הזה

לדעתי אני האדם המתאים לפרויקט הזה כי:

• יש לי ניסיון בעבר בשיפור מסמכי התיעוד של ארגונים ואני יכול להשתמש בכל מערכת לניהול גרסאות, כך ביצוע פקודות ב-Gitab לא יהיה בעיה. בנוסף, מה שמניע אותי הוא לעבוד על פרויקטים שיוצרים ערך לאנשים.
• לדעתי, אם רוצים שמישהו יעשה משהו בצורה היעילה ביותר, צריך לתעד אותו. תיעוד התהליכים שלכם מבטיח יעילות, עקביות ושקט נפשי לכל המעורבים.
• אני מכירה את הצרכים של משתמשי VLC כי אני אחד מהם. השיתוף יאפשר לך לכתוב את התיעוד כך שכל משתמש אחר בעולם יבין אותו במבט ראשון.