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