בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- VLC
- כותבים טכניים:
- Avii
- שם הפרויקט:
- יצירת מסמכי התיעוד למשתמשי VLC לגרסה אחת לנייד (Android)
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
ABSTRACT
מסמכי העזרה משמשים כמערכת תמיכה סטטית כדי לעזור למשתמשי הקצה. היא מספקת מידע טכני וגם מידע לא טכני על מוצר או שירות. היא עוזרת למשתמשים ללמוד איך להשתמש בתוכנה או בשירות. לא כל אחד רוצה ליצור קשר עם התמיכה או להמתין לתשובה באימייל אם כל מה שהוא צריך הוא קצת הנחיות, טיפים או טריקים. מסמכי התיעוד למשתמשים עושים בדיוק את זה. הוא גם מפחית את עלויות התמיכה ומשמש כזהות לתקינות המוצר ולצוות המפתחים.
אפליקציית VLC ל-Android הורדה יותר מ-100 מיליון פעמים מחנות Google Play בלבד. ל-VLC יש הרבה תכונות בגרסאות לנייד, החל מהפעלת אודיו-וידאו ועד לסטרימינג ברשת. לרוב, אנשים רוצים להשתמש בתכונות האלה אבל לא מצליחים. חיפוש בלוג או סרטון אקראי לצורך כך דורש הרבה זמן וסבלנות, ועדיין אין ערובה לאמיתות המידע שהתקבל. נכון לעכשיו, ב-VLC מתארחים מסמכי העזרה של VLC ל-Android בדף הוויקי, והתיאור של התכונות האלה מצומצם או לא קיים. בנוסף, דפי הוויקי עודכנו לאחרונה במרץ 2019. הפרויקט הנוכחי יספק מסמכי עזרה חדשים למשתמש עם עיצוב מודרני וקלות שימוש רבה יותר לגרסה ל-Android.
המצב הנוכחי
דפי הוויקי מיושנים לחלוטין ומכילים מעט מאוד מידע על הגרסה האחרונה של VLC. בנוסף, קשה לנווט בהם. אין אפשרות גלויה לקרוא את המסמכים במסמכים בשפה אחרת מלבד אנגלית. הוא לא מכיל בכלל תיאורים של תכונות.
ניתוח
-> נכון לעכשיו, התיעוד הנוכחי מיושן וצריך לכתוב אותו בדרך חדשה ולהשתמש בפלטפורמה ובכלים אחרים.
-> לרוב המשתמשים ב-Android יש ידע טכני מועט או שאין להם ידע כזה בכלל. אבל יש אנשים שצריכים מידע טכני יותר על תכונה מסוימת. לא מומלץ לכתוב ולתחזק שני מסמכי תיעוד נפרדים לכל אחת מהמטרות שלמעלה. או אפילו באותו תיעוד חלוקת תכונה על בסיס טכני ולא טכני יוצרת בלבול נוסף. שוב, רוב המשתמשים רגילים לממשק המשתמש שהם רואים או לתכונות שבהן הם משתמשים, ולכן לא קל לכולם להחליט אם משהו הוא טכני או לא טכני. לכן אנחנו רוצים לפשט את התהליך עבורם.
-> רוב המשתמשים ינסו לקבל מידע דרך הסמארטפון עצמו, והשאר ינסו לקבל מידע דרך המחשב או מכשירים אחרים. לכן, חשוב שהמסמכים יהיו קלים להתאמה לכל גודל מסך. והן לא יוצרות בלבול לגבי הניווט.
-> לא כל התכונות של גרסת המחשב זמינות בגרסת Android, ואם הן זמינות, הן לא פועלות באותו אופן בשתי הגרסאות. הסיבה לכך היא שהאפליקציה למחשב שולחני הייתה בפיתוח במשך זמן רב יותר, והיא הגיעה למצב של 'השגת רמת שיא'. לעומת זאת, הגרסה לנייד חדשה יחסית ועדיין נמצאת בפיתוח. חוץ מזה, למרות שמכשירים ניידים נהיים חזקים יותר ויותר, יש הגבלה ברורה על סוג התכונות שאנחנו יכולים לשלב, בעיקר בגלל הביקוש של משתמש הקצה. אם יש תכונה שאף אחד לא משתמש בה, זה בזבוז של משאבי הפיתוח. לכן לא מומלץ להשתמש בשני המסמכים על סמך תכונות.
על סמך הניתוח, אני מציע את הדברים הבאים. 1. נכון לעכשיו, במסמכי התיעוד למשתמשי מחשב נעשה שימוש ב-Sphinx Documentation Generator ובעיצוב של Read the Docs. שימוש באותו פורמט לגרסה ל-Android יעזור לנו בדרכים הבאות: -> מיזוג קל של שתי המסמכי העזרה. -> הוא מותאם לכל גודלי המסכים. -> חוויה חלקה במעבר למסמכי התיעוד למשתמשי Android דרך מסמכי התיעוד למחשב
- הפרדת הפרקים, הקטעים והקטעים המשניים לפי המיקום היחסי שלהם בבקשה. לדוגמה: מצב 'רקע'/'תמונה בתוך תמונה' נמצא בתוך סמל האפשרויות הנוספות -> הגדרות->סרטון, ולכן מבנה הפרקים יהיה
- עוד
- |__הגדרות
- | |__ספריית המדיה
- | |__סרטון --> מצב רקע/מצב PiP
- : -> הגישה הזו תשפר את נוחות הגישה, כי המשתמשים יוכלו לנווט בקלות לחלק שבו הם זקוקים לעזרה על ידי השוואה למיקום היחסי באפליקציה. לכל אחת מהתכונות אפשר להפריד בין חלקים טכניים לחלקים לא טכניים. קודם נכתוב תיאור פשוט ולא טכני, ואז נמשיך להדגיש או לתייג חלקים טכניים של אותה תכונה, אם יש כאלה, מתחת לתיאור. הפעולה הזו עשויה להוביל לחזרות מסוימות, אבל היא תבטיח חוויה חלקה גם אם הרוב לא טכני. כך תוכלו לשפר את יכולת התחזוקה בעתיד. מכיוון שהאפליקציה תגיע למצב של רוויה, סביר להניח שממשק המשתמש היחסי לא ישתנה הרבה, כך שבעתיד, אם תתווסף או תוסר תכונה חדשה, נוכל פשוט לבצע רפאקציה של הקטע. אם כל ממשק המשתמש ישתנה, נוכל לסדר מחדש את הקטעים או הפרקים או לשנות את המבנה של המסמך כולו. בכל מקרה, נצטרך לשנות את כל המסמך כי צילום המסך צריך להשתנות כך שיתאים לממשק המשתמש הנוכחי. הדגמה עובדת מתארחת כאן : https://avinal.gitlab.io/vlc-android-docs/
כל קטע בתיעוד יכלול צילום מסך מתויג , תיאור של התכונה, חלק טכני יותר אם יש טיפים וטריקים לגבי התכונה.
-> פיתוח עצמאי של מסמכי התיעוד האלה למשתמש מהמחשב יעזור לנו למזג את שני מסמכי התיעוד בכמה שלבים בלבד, בלי להשפיע על מסמכי התיעוד הקיימים או להיות מושפעים מהם במהלך הפיתוח. אני מציע להציב את כל המסמכים האלה בקטע Android במסמכי העזרה למחשב, אחרי שהם יתווספו, ואז ליצור קישור קבוע לתיעוד של VLC ל-Android.
-> שיפורים נוספים עשויים לכלול עיצוב מחדש של דף הבית של מסמכי העזרה למשתמשי Desktop, כדי לאפשר למשתמשים לבחור ישירות את מערכת ההפעלה המועדפת עליהם, ולאחר מכן להפנות אותם למסמכי העזרה של מערכת ההפעלה שנבחרה. מאחר שמסמכי התיעוד למשתמשי VLC ב-Windows, ב-MacOS וב-Linux כבר עוצבו ונוסחו בצורה טובה, יכול להיות שנציג אפשרויות לבחירה מבין Windows/MacOS/Linux או Android או iOS. כך תוכלו ליצור מסמכי עזרה נפרדים אך אחידים למשתמש, עם קישור אחד בלבד לכל היציאות.
למה המסמך המוצע שלי למשתמשים טוב יותר? מסמכי התיעוד המוצעים למשתמשים בנויים על סמך הדפוסים הנפוצים שבהם נוהגים משתמשי הקצה לקבל עזרה. במסמכי העזרה משולבות כל התכונות הנדרשות, למשל: פשטות, בהירות, מראה ותחושה, ידע טכנולוגי, כדי למקסם את קלות השימוש ואת חוויית משתמשי הקצה. בנוסף, אפשר לתחזק את הדוח בקלות כי כבר אין צורך לתחזק תיעוד נפרד למשתמש עבור כל יציאה.
למה אני האדם המתאים לפרויקט הזה? -> אני כותב קודים כבר שנתיים, ולעיתים קרובות אני צריך לעיין במסמכי העזרה של ה-API לספריות מסוימות או לתוכנות מסוימות, או אפילו לתעד את הקוד שלי. כך אני יודע בדיוק מה אנשים רוצים לראות במסמכי העזרה, באיזו בעיה הם נתקלים ואיך הם פונים לקבלת עזרה. אוכל להשתמש באותה ניסיון כדי לכתוב מסמכי עזרה עקביים וקלים לקריאה.
-> כתבתי באופן פעיל תוכן טכני ב-Quora, ב-Stack Overflow ובפלטפורמות אחרות. אני יודע להסביר דברים בצורה מושכת וקל לאנשים להבין.
-> VLC ל-Android הוא כלי חזק ומפורסם מאוד, אבל רוב התכונות שלו לא ידועות או שאין לגביו עזרה זמינה. אני משתמש ב-VLC גם בפלטפורמות למחשב וגם לנייד כבר הרבה שנים, ואני יודע עם אילו בעיות המשתמש עשוי להיתקל. אני יכול להבטיח תיעוד מצוין על סמך כל הידע והניסיון שלי.