דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של 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, ומהיכולת לתרגם תיעוד.
לקריאת המסמכים
קראו את Google Docs כדי לפשט את תיעוד התוכנה על ידי בנייה, ניהול גרסאות ואירוח של המסמכים שלכם באופן אוטומטי. הכלי אף פעם לא יוצא להסתנכרן, כלומר, בכל פעם שאתם שולחים קוד למערכת בקרת הגרסאות המועדפת עליכם - Git, Mercurial, Bazaar או Subversion, Read the Docs יבנה את המסמכים שלכם באופן אוטומטי, כך שהקוד והתיעוד שלכם תמיד יהיו מעודכנים. יש לה מספר גרסאות; קרא את Docs יכול לארח ולבנות גרסאות מרובות של המסמכים שלך, כך שגרסה 1.0 של המסמכים וגרסה 2.0 של המסמכים שלך קלה כמו הסתעפות או תג נפרדים במערכת בקרת הגרסאות. Google Docs הוא שירות חינמי, מבוסס על קוד פתוח ומארח תיעוד של כמעט 100,000 פרויקטים גדולים וקטנים של קוד פתוח, כמעט בכל שפה אנושית ושפת מחשב.
רציף
Sphinx הוא כלי עוצמתי במיוחד, ו-Read the Docs מובנה למעלה כדי לספק אירוח לתיעוד של Sphinx ששומר על המסמכים שלכם מעודכנים בכל הגרסאות. ביחד, מדובר בקבוצה נפלאה של כלים שמפתחים וכותבים טכניים יכולים להיעזר בהם כדי ליצור מסמכי תיעוד למשתמש שהכי מתאימים למשתמשי הקצה.
הספינקס כוללת תמיכה בתרגום מסמכים למספר שפות. יש בו תמיכה בניהול גרסאות שישמש לניהול התיעוד. בניגוד ל-wiki הנוכחי, שבו כל אחד יכול לערוך ולא להוסיף את המידע הנכון, המערכת הזו לניהול גרסאות מבטיחה שכל השינויים ייבדקו קודם לפני שהם ימוזגו למאגר הראשי. בקרת גרסאות גם תאפשר לתיעוד להגדיל את התרומה של הקוד הפתוח לפרויקט, מכיוון שאנשים יכולים ליצור בעיות, בקשות משיכה פתוחות וכו'. Sphinx וקוראים את Docs משמשים רשימה של קהילות נהדרות ונהדרות אחרות כמו ASP.NET, Kernel, Julia, Jupyter, PHPMyAdmin, כתיבת המסמכים וכו', זהו כלי מצוין לשימוש לתיעוד המשתמש החדש של VLC.
לא רק קראתי על הכלים האלה, אלא יצרתי גם טעימה בסיסית. זה הקישור: https://gitlab.com/Didicodes/demo-vlc-user-documentation למאגר Gitlab שלי. את הגרסה המתארחת ב-Readthedocs אפשר למצוא כאן: [https://vlc-user-document-demo.readthedocs.io/en/minute/](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 Internationalization.
- יש לעודד את קהילת התיעוד כדי שמשתמשים יוכלו לדווח או לפתור בעיות שהם נתקלים בהן בזמן קריאת התיעוד.
למה כדאי להשתמש בפרויקט הזה?
תמיד האמנתי בכתיבת קוד, פתרון בעיות ובניית תוכנה, שמממשים את מלוא הפוטנציאל שלהם כאשר יש לכם גם אפשרות להעשיר את הידע של אנשים אחרים באמצעות כתיבה. תמיד הוקסמתי מהמאמצים של קהילת VideoLAN ליצירת פתרונות תוכנה חינמיים למולטימדיה. כילד, נגן המדיה של VLC תמיד היה התוכנה שהשתמשתי בה להאזנה למוזיקה או לצפייה בסרט, כי הוא היה חזק מאוד והיה מורכב מכל כך הרבה תכונות. זה יהיה כבוד לעבוד עם הקהילה שתרמה להפוך את ילדותי למדהימה.
למה אני האדם המתאים לביצוע הפרויקט הזה
אני מאמין שאני האדם הנכון לפרויקט הזה, כי:
- יש לי ניסיון בעבר בשיפור התיעוד של ארגונים ואני יכול להשתמש בכל מערכת לניהול גרסאות, כך שביצוע פקודות ב-Gitab לא יהיה בעייתי. בנוסף, מה שמניע אותי הוא לעבוד על פרויקטים שיוצרים ערך לאנשים.
- אם אתם רוצים שמישהו יעשה משהו בצורה היעילה ביותר, אתם מתעדים אותו. תיעוד התהליכים שלכם מבטיח יעילות, עקביות ושקט נפשי לכל המעורבים.
- אני מכיר את הצרכים של משתמשי VLC כי אני אחד מהם. הם יוכלו לכתוב את התיעוד כך שכל משתמש אחר בעולם יבין אותו במבט ראשון.