בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- ScummVM
- כותבים טכניים:
- קאדי
- שם הפרויקט:
- השקת פורטל תיעוד
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
היעדים:
- כדי ליצור מסמכי עזרה באיכות גבוהה עם גרסאות למשתמשי קצה, על ידי איחוד כמויות גדולות של מידע ממקורות שונים וכתיבה מחדש של מידע כדי לשפר את הבהירות, העקביות והשלמות שלו.
- המסמכים צריכים להיות קלים להבנה למתחילים, בלי להתייחס למשתמשים בעלי ידע טכני כאל ילדים.
- כדי ליצור פורטל מסמכי עזרה באמצעות מחולל אתר סטטי.
- כדי לספק מסמכי תיעוד למשתמשי קצה שמוכנים לעתיד, על ידי יצירת תבניות והוראות מפורטות לתורמים עתידיים בקוד פתוח.
המצב הנוכחי:
- מסמכי התיעוד הזמינים בנושא ScummVM מפוזרים בין מספר מקורות.
- קשה למצוא את המידע, ולעיתים קרובות הוא משוכפל. קל ללכת לאיבוד בדפים לא ברורים.
- קשה לדעת איזה מידע עדכני ואיזה מידע לא.
- חלק מהמידע חסר או חלקי.
פתרון הבעיה:
מבנה מומלץ למסמכי התיעוד:
דף נחיתה
|-- תחילת העבודה
| -- Quick start guide
|-- Installing ScummVM
| |-- Nintendo 3DS
| |-- AmigaOS
| |-- Android
| |-- (every)
| |-- (common)
| |-- (supported)
|-- (פלטפורמה)
|-- שימוש ב-ScummVM
| |-- מרכז האפליקציות
| |-- הגדרות גלובליות
| |-- הגדרות המשחק
| -- Keyboard shortcuts
|-- Advanced options
| |-- Cloud and LAN
| |-- Control Mapping
| |-- Configuration
| |-- Command line options
| |-- Graphics
|-- מוזיקה וצלילים
|-- עזרה
| |-- שאלות נפוצות
| |-- אנשי קשר
| |-- בעיות ידועות
| -- Reporting a bug
|-- Game Notes-- הערות לגרסה
- תחילת העבודה:
משתמשים חדשים בדרך כלל מחפשים מדריך למתחילים כדי להתחיל במהירות האפשרית. התקנת ScummVM יכולה להיות מורכבת בפלטפורמות מסוימות, אבל התקנה במחשב היא פשוטה.
המדריך למתחילים עוסק בנושאים הבאים:
- איך מתקינים את ScummVM ב-Windows, Mac ו-Linux.
איך טוענים, מוסיפים ומפעילים משחק.
התקנת ScummVM:
במקרים שבהם ההתקנה לא אינטואיטיבית, או במקרים שבהם למשתמש אין בסיס טכני חזק, המשתמש זקוק למדריך מקיף להתקנת ScummVM בכל אחת מהפלטפורמות הנתמכות.
כל דף התקנה מקיף צריך לכלול את הפרטים הבאים:
- כל דרישות המערכת או התנאים המוקדמים.
- איך מורידים את הגרסה המתאימה של ScummVM.
- איך מתקינים את ScummVM.
- איך לטעון משחקים לפלטפורמה שנבחרה, במיוחד אם זו לא הפלטפורמה שבשבילה המשחק תוכנן.
איך מריצים את ScummVM, מוסיפים משחק ומפעילים אותו.
שימוש ב-ScummVM:
המשתמשים צריכים מסמכי עזר שמסבירים איך להשתמש ב-ScummVM.
מסמכי העזרה צריכים לכלול את הפרטים הבאים:
- ממשק מרכז האפליקציות: איך נראים כל חלון וכרטיס ואיך הם פועלים.
- הסבר על ההגדרות הזמינות, הן הגדרות כלליות והן הגדרות ספציפיות למשחק.
מקשי קיצור.
אפשרויות מתקדמות:
משתמשים מתקדמים זקוקים למידע טכני נוסף על האפשרויות הזמינות להם לשינוי אופן הפעלת המשחקים.
- הערות על המשחק:
כל מידע ספציפי למשחק שהמשתמשים צריכים לדעת, כולל, בין היתר: - תכונות ייחודיות של ההתקנה - קבצים נוספים שנדרשים - אמצעי בקרה חריגים או שונים
- בעיות מוכרות:
הקטע הזה צריך לכלול באגים ידועים שספציפיים לגרסה.
- נתוני גרסה:
אמנם תיעוד שלנו יהיה מחולק לגרסאות, אבל כדאי לכלול קטע של הערות לגרסה כדי לספק סיכום של השינויים בגרסה האחרונה. יכול להיות שזה יכלול תחומים מסוימים שכרגע לא נכללים במסמכי העזרה האלה, כמו משחקים חדשים שנתמכים או מידע על מנועים חדשים.
תוכנית ההתקפה:
אני מציע להתחיל ליצור תבנית לדפים של התקנת ScummVM, כי זו תהיה הדרך הקלה ביותר לקבל את המידע הנדרש ממפתחים או ממנהלי פורטים (במיוחד במקרים שבהם המידע הזה מצומצם או לא קיים). אמלא מראש את כל המידע שכבר יש לי במסמכים קיימים, ולאחר מכן אוכל לבדוק את השלמות, הדיוק והמטבע, או להוסיף אותם לפי הצורך.
בשלב הבא אבדוק את המסמכים הקיימים: README, Wiki והאתר. ככל שאמשיך, אכתוב מחדש ותוסיף אותם לכל קטע לפי הצורך, ואעביר את כל המידע לפורטל החדש. בנוסף, אסמן מהיכן יישלף המידע, כדי לוודא שכשהפורטל יהיה פעיל לא יהיו כפילויות, סתירות או חריגות אחרות.
לאורך התהליך אעבוד עם המנטורים, המפתחים, מנהלי הפורטים ומומחים אחרים בתחום כדי למצוא מקור למידע חסר, וגם כדי לוודא שכל דף יהיה עדכני ומקיף ככל האפשר.
מתוך רצון לשתף פעולה, בכפוף לאישור מהמנחים, אני רוצה לאפשר לקהילת ScummVM לגשת לפורטל של העבודה המתמשכת במהלך תהליך הכתיבה, כדי לקבל משוב בזמן אמת ולוודא שלא פספסנו שום דבר.
מומלץ להשתמש במדריך סגנון, כמו מדריך הסגנון לכתיבת מסמכים למְפַתְּחִים ב-Google, כדי לשמור על עקביות בעבודת המחקר הזו ובכל המסמכים שייכתבו מעכשיו והלאה.
כשהדבר אפשרי, אשתמש בצילומי מסך, בקובצי GIF ובכלים חזותיים אחרים כדי להקל על ההבנה.
לוח זמנים מוצע:
יצירת קשרים בקהילה 17 באוגוסט עד 13 בספטמבר 2020
כדאי להמשיך להקדיש זמן לשיחות עם המנטורים ועם הקהילה הרחבה יותר של ScummVM כדי לשפר את החזון של הפרויקט ולגבש את הפרטים האחרונים, כמו מבנה המסמך והתוכן שלו.
שבוע 1 14 בספטמבר עד 20 בספטמבר
- יוצרים תבנית לדפי ההתקנה הספציפיים לפלטפורמה.
- ממלאים מראש את התבניות במידע הקיים ומפיצים אותן למפתחים או למנהלי הפורטים המתאימים לקבלת מידע נוסף.
שבוע 2 21 בספטמבר עד 27 בספטמבר
- הגדרת פורטל התיעוד החדש.
שבוע 3 28 בספטמבר עד 4 באוקטובר
שימוש ב-ScummVM: - הממשק - הגדרות גלובליות התקנת ScummVM: - מוחזרות מדריכי התקנה ספציפיים לפלטפורמה, לאחר שתבניות שהושלמו.
שבוע 4 5 באוקטובר עד 11 באוקטובר
שימוש ב-ScummVM: - הגדרות המשחק - קיצורי דרך במקלדת התקנת ScummVM: - מדריכי התקנה ספציפיים לפלטפורמה, כאשר התבניות המלאות יחזרו אליי
שבוע 5 12 באוקטובר עד 18 באוקטובר
אפשרויות מתקדמות: - Cloud ו-LAN - מיפוי בקרה התקנת ScummVM: - מדריכי התקנה ספציפיים לפלטפורמה, כאשר התבניות המלאות יחזרו אליי
שבוע 6 19 באוקטובר עד 25 באוקטובר
אפשרויות מתקדמות: - הגדרה - אפשרויות בשורת הפקודה התקנת ScummVM: - מדריכי התקנה ספציפיים לפלטפורמה, כאשר התבניות המלאות יחזרו אליי
שבוע 7 26 באוקטובר עד 1 בנובמבר
אפשרויות מתקדמות: - גרפיקה - אודיו התקנת ScummVM: - מדריכי התקנה ספציפיים לפלטפורמה, כאשר התבניות המלאות יחזרו אליי
שבוע 8 2 בנובמבר עד 8 בנובמבר
עזרה: - שאלות נפוצות - אנשי קשר - בעיות מוכרות
התקנת ScummVM: - מדריכי התקנה ספציפיים לפלטפורמה, כי התבניות המלאות יחזרו אליי
שבוע 9 9 בנובמבר עד 15 בנובמבר
עזרה: - דיווח על באגים - הערות על משחקים - נתוני גרסאות
התקנת ScummVM: - השלמת מדריכי פלטפורמה שעדיין לא הושלמו.
שבוע 10 16 בנובמבר עד 22 בנובמבר
- עריכה סופית, הגהה וסיום של כל ההחלטות שקשורות לפורטל, כמו ניווט בסרגל הצד, שינויים בנושא העיצוב או ב-CSS וכו'.
- מוודאים שכל הקישורים פועלים כצפוי.
- מוודאים שהתמונות או ה-GIF מוצגים בצורה תקינה.
שבוע 11 23 בנובמבר עד 30 בנובמבר
- משלימים את הטיפול בפריטים שעדיין לא הסתיימו ומשיקים את הפורטל באופן רשמי.
- אחרי השקת הפורטל, מסירים מידע מיותר ממקורות אחרים, תוך התייעצות עם המנטורים.