דף זה מכיל את הפרטים של פרויקט כתיבה טכני שהתקבל בעונת 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 גם בפלטפורמות למחשבים וגם בפלטפורמות לנייד כבר הרבה שנים, ואני יודע מה הבעיות שאנשים עשויים להיתקל בהן. באמצעות שילוב של כל הידע והניסיון שלי, אוכל להבטיח תיעוד מעולה.