בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- VideoLAN
- כותבים טכניים:
- Edidiong Anny Asikpo
- שם הפרויקט:
- מודרניזציה (שכתוב) של מסמכי התיעוד למשתמש של VLC
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
ABSTRACT
מסמכי התיעוד למשתמש נועדו לעזור למשתמשי הקצה להשתמש במוצר או בשירות. תיעוד משתמש טוב הוא חשוב מאוד כי הוא מספק למשתמשים דרך ללמוד איך להשתמש בתוכנה, להכיר את התכונות שלה, לקבל טיפים וטריקים ולפתור בעיות נפוצות שנתקלים בהן בזמן השימוש בתוכנה. בנוסף, היא מפחיתה את עלות התמיכה והיא חלק מהזהות הארגונית של המוצר: תיעוד משתמש טוב הוא סימן לבריאות המוצר ולבריאות צוות הפיתוח.
בלי מסמכי עזרה טובים למשתמש, יכול להיות שהמשתמש לא ידע איך לבצע את הפעולות שלמעלה בצורה יעילה וחסכונית. מסמכי עזרה למשתמש יכולים למלא תפקיד מרכזי בהבטחת ההצלחה של מוצר, כי תקשורת טובה תמיד תהיה בלב ליבה של כל עסק או מוצר, ומסמכי עזרה טובים פשוט מעבירים את התקשורת הזו למסגרת ניהולית שכל אחד יכול לגשת אליה כדי להצליח.
נכון למועד הכתיבה הזו, ניגשו לתיעוד המשתמש של VLC 4,634,065 פעמים וההורדה של נגן המדיה VLC מתבצעת בערך 23 מיליון פעמים בחודש מהאתר הראשי. זה מראה שהרבה אנשים ברחבי העולם משתמשים ב-VLC Media Player ואולי ירצו לקרוא את מסמכי התיעוד של המשתמש שלו כדי לקבל הדרכה לגבי אופן השימוש בנגן המדיה. עם זאת, מסמכי התיעוד למשתמש של נגן המדיה VLC לא מעודכנים וערוכים באופן חלקי (השינוי האחרון בוצע ב-28 באוקטובר 2015), וקהילת VideoLAN רוצה להשתמש בפרויקט הזה כדי לשפר את מסמכי התיעוד למשתמש שלה, כדי לאפשר למשתמשי הקצה ליהנות מחוויית שימוש חלקה בנגן המדיה VLC.
המצב הנוכחי
בשלב זה, מסמכי התיעוד למשתמשים זמינים בדף בוויקי. האתר לא מעודכן, חלקי, קשה לנווט בו או למצוא בו מידע, הוא לא מכיל מידע על הגרסה הנוכחית של נגן המדיה ואפשר לתרגם אותו רק לגרמנית, מה שגורם לבעיה גדולה לאנשים שלא יודעים לקרוא באנגלית.
למה המסמך שלי לשימוש המשתמשים הוא שיפור על פני המסמך הנוכחי?
המסמכים המוצעים למשתמש יותאמו כדי לשפר את היעילות, העקביות והשקט הנפשי של משתמש הקצה. המדריך יכלול מדריכים כתובים ותמונות משויכות, הוראות והסברים על השימוש בכל תכונה של נגן המדיה VLC, יהיה עדכני, קל לניווט, מובן וניתן לתרגום לפחות לחמש שפות עיקריות.
מנחים: Jean-Baptiste, Alex, Simon
ניתוח
שוחחתי עם Jean-Baptiste על הסביבה החדשה שאליה יעברו מסמכי העזרה הנוכחיים של המשתמשים לצורך שיפורים. הוא שיתף איתי שני קישורים: אחד למאגר Gitlab של קובץ המקור שנכתב באמצעות Sphinx, והשני למסמכי העזרה הראשיים שמתארחים ב-Read the Docs. הוא אמר שהם מצפים שהמסמכים החדשים יהיו דומים למסמכים האלה. בדקתי הרבה על הכלים האלה כדי להבין טוב יותר איך הם פועלים.
ספינקס
Sphinx הוא פתרון חזק ומשופר ליצירת מסמכי עזרה לתוכנות. הוא כולל כמה תכונות שכותבים מצפים להן, כמו פרסום ממקור יחיד, שימוש חוזר בתוכן באמצעות הטמעות, הטמעות מותנות על סמך סוג התוכן והתגים, כמה עיצובים מתקדמים של HTML שמספקים חוויית משתמש נהדרת בנייד ובמחשב, הפניה לדפים, למסמכים ולפרויקטים, תמיכה באינדקס ובמילון ותמיכה בבינלאומיזציה. בנוסף, הוא משתמש ב-reStructuredText כשפת ה-markup שלו, ורבים מהיתרונות שלו נובעים מהעוצמה והפשטות של reStructuredText ומהיכולת שלו לתרגם מסמכי תיעוד.
Read the Docs
Read the Docs מפשט את תיעוד התוכנה על ידי אוטומציה של ה-build, ניהול הגרסאות והאירוח של המסמכים. המערכת תמיד מסונכרנת. כלומר, בכל פעם שדוחפים קוד למערכת בקרת הגרסאות המועדפת, בין אם מדובר ב-Git, ב-Mercurial, ב-Bazaar או ב-Subversion, המערכת של Read the Docs תיצור את המסמכים באופן אוטומטי כדי שהקוד והמסמכים תמיד יהיו מעודכנים. יש לו מספר גרסאות. אפליקציית Docs יכולה לארח ולבנות גרסאות מרובות של המסמכים שלכם, כך שתוכלו להשתמש בגרסה 1.0 של המסמכים שלכם ובגרסה 2.0 של המסמכים שלכם בקלות כמו ליצור הסתעפות או תג נפרדים במערכת לניהול גרסאות. Read the Docs הוא אתר חינמי בקוד פתוח שמארח מסמכי עזרה לכמעט 100,000 פרויקטים גדולים וקטנים בקוד פתוח, כמעט בכל שפה אנושית ומחשבית.
VERDICT
Sphinx הוא כלי חזק מאוד, ו-Read the Docs מבוסס עליו כדי לספק אירוח למסמכי העזרה של Sphinx, כך שהמסמכים יישארו עדכניים בכל הגרסאות. יחד, הם מהווים קבוצה נהדרת של כלים שמפתחים וסופרים טכניים יכולים להשתמש בהם כדי ליצור מסמכי עזרה למשתמש שיתאימו בצורה הטובה ביותר למשתמשי הקצה.
ב-Sphinx יש תמיכה בתרגום מסמכי עזרה למספר שפות. הוא תומך בבקרת גרסאות, שתשמש לניהול המסמכים. בניגוד לוויקי הנוכחי, שבו כל אחד יכול לערוך את המידע ולא תמיד להוסיף את המידע הנכון, מערכת בקרת הגרסאות הזו תבטיח שכל השינויים ייבדקו לפני שהם ימוזגו למאגר הראשי. בקרת הגרסאות תאפשר גם להגדיל את התרומות של קוד פתוח לפרויקט, כי אנשים יוכלו ליצור בעיות, לפתוח בקשות משיכה וכו'. יש רשימה ארוכה של קהילות ומוצרים אחרים שמשתמשים ב-Sphinx וב-Read the Docs, כמו ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, Write the Docs ועוד. זהו כלי מצוין לשימוש במסמכי העזרה החדשים של VLC.
לא קראתי רק על הכלים האלה, גם יצרתי דוגמה בסיסית. זה הקישור: https://gitlab.com/Didicodes/demo-vlc-user-documentation למאגר Gitlab שלי. אפשר למצוא את הגרסה המתארחת ב-readthedocs כאן: [https://vlc-user-Documents-demo.readthedocs.io/en/previous/](https://vlc-user-docs-demo.readthedocs.io/en/previous/).
המבנה של המסמכים המוצעים
יצרתי מבנה למסמכי התיעוד למשתמש של VLC שניתן למצוא כאן; https://docs.google.com/document/d/1Sy2V2IADoCyfnGBK70v8mkjiWK2tH-oWdUlDxAfQAYA/edit?usp=sharing. לפני תחילת ההטמעה של המבנה החדש, הוא צריך לקבל אישור מהמנחים. כלומר, סביר להניח שהמבנה ישתנה אחרי שהוא ייבדק על ידי המנטורים.
יעדי הפרויקט
- משנים את מבנה המסמך.
- צריך לעדכן את התיעוד כך שיתאים לגרסאות המודרניות של VLC.
- העברת מסמכי העזרה למשתמשים ל-Gitlab באמצעות Sphinx ו-ReadtheDocs.
- מסירים תמונות ומידע מיושנים.
- משכתבים את מסמכי התיעוד למשתמש כדי שיהיה קל יותר להבין אותם.
- מגדירים אותו לתרגום באמצעות התכונה Sphinx Internationalization.
- כדאי ליצור קהילה שמנהלת את מסמכי העזרה, כדי שהמשתמשים יוכלו לדווח על בעיות שנתקלו בהן בזמן הקריאה או לפתור אותן.
למה כדאי לפרויקט הזה?
תמיד האמנתי שכתיבה של קוד, פתרון בעיות ופיתוח תוכנה מגיעים למיצוי הפוטנציאל שלהם כשיש לכם גם את היכולת להאיר את עיניהם של אחרים בנושא באמצעות כתיבה. באופן אישי, תמיד ריתקו אותי מהמאמצים של קהילת VideoLAN ליצירת פתרונות תוכנה חינמיים למולטימדיה. כשגדלתי, נגן המדיה VLC היה תמיד התוכנה שבה השתמשתי כשהקשבתי למוזיקה או צפיתי בסרט, כי הוא היה חזק מאוד והכיל הרבה תכונות. זה יהיה כבוד לעבוד עם הקהילה שתרמה לכך שהילדות שלי הייתה מדהימה.
למה אני האדם המתאים לפרויקט הזה
לדעתי אני האדם המתאים לפרויקט הזה כי:
- יש לי ניסיון בעבר בשיפור המסמכים של ארגונים, ואני יכול להשתמש בכל מערכת בקרת גרסאות, כך שאין לי בעיה לבצע פקודות ב-Github. בנוסף, מה שמניע אותי הוא העבודה על פרויקטים שיוצרים ערך לאנשים.
- לדעתי אם רוצים שמישהו יבצע פעולה כלשהי באופן היעיל ביותר, עליך לתעד זאת. תיעוד התהליכים מבטיח יעילות, עקביות ושקט נפשי לכל מי שמעורב.
- אני מכיר את הצרכים של משתמשי VLC כי אני אחד מהם. כך תוכלו לכתוב את המסמכים כך שכל משתמש ברחבי העולם יוכל להבין אותם במבט ראשון.