בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- SciPy
- כותבים טכניים:
- mkg33
- שם הפרויקט:
- מסמכים שמתמקדים במשתמשים ושינוי מבני מעמיק
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
מוטיבציה:
אני מתכוון לעבוד על עיבוד מחדש של המסמכים הקיימים, כדי שיהיה קל למשתמשים עם צרכים שונים לגשת אליהם. מובן מאליו שחוקר כנראה יתעניין בתכונות מתקדמות ועדינות, בעוד שמשתמש ללא מומחיות קודמת יעריך מדריכים מפורטים ותרשימים.
אני רוצה להמשיך בפרויקט הזה מסיבות אישיות ומקצועיות: קודם כול, אני רוצה לתרום משמעותית ל-SciPy כי המחקר שלי נהנה ממנו מאוד. שנית, אני נתקל לעיתים קרובות במסמכי עזרה לא מספיקים (או חסרים) בתוכנות אחרות, ותמיד תוהה כמה מהר יותר (אם בכלל!) המשתמשים היו יכולים ללמוד איך להשתמש בקוד אם היו מקבלים מדריך מקיף.
יעדים:
אני רוצה לשפר את המסמכים הקיימים של SciPy מבחינת תוכן וגרפיקה. החלק החשוב ביותר בגישה שלי לבעיה הזו הוא הפריסה והניתוח של סקר המשתמשים. כלומר, סקר קצר שנערך באינטרנט ומאפשר למשתמשים שונים להביע את הצרכים שלהם בנוגע למסמכי התיעוד. אני מאמין/ה שהדעות שלהם צריכות להיות מקור להשראה (איך נוכל ליצור תיעוד ידידותי יותר למשתמש?).
בנוגע להוצאה לפועל של הפרויקט עצמו, בשלב הראשון נבצע תכנון וניתוח של סקר המשתמשים, ונטפל בכמה בעיות סגנוניות ששמתי לב אליהן במסמכים הנוכחיים. לדוגמה, חוסר עקביות (לדוגמה: מערכים דו-ממדיים שמופיעים לצד מערכים דו-ממדיים), משפטים מורכבים שצריך לכתוב מחדש או חוסר סדר אלפביתי בדפי משנה מסוימים. השלב השני יתמקד במבוא של מדריכים גרפיים שמכילים היפר-קישורים לנושאים הרלוונטיים (על סמך תוצאות הסקר ובקשות אחרות לקהילה). בטווח הארוך, אני רוצה ליצור מסמכי עזרה יעילים שמותאמים לסוגים שונים של משתמשים. בנוסף, אנסה להפוך את המדריכים לעקביים יותר מבחינה לשונית ומבחינה מבנית. לבסוף, אני מתכוון לכתוב מדריכים חדשים (בהתאם לצרכים הנוכחיים של הקהילה).
סקר משתמשים:
בנוגע לסקר המשתמשים, אני מציע להשתמש ב-Google Forms מכמה סיבות. קודם כול, Google Forms הוא כלי חינמי שמציע פונקציונליות בלתי מוגבלת (מבחינת מספר המשיבים, השאלות וכו'), הוא כולל טופס חזותי אטרקטיבי, את אפשרויות הסקר השימושיות ביותר (למשל, סולם לינארי להתאמה אישית, תיבות סימון ושאלות אמריקאיות) והכי חשוב, אפשר לייצא את התוצאות בקלות לצורכי ניתוח סטטיסטי. על סמך מחקר באינטרנט, נראה ש-Google Forms הוא הכלי החינמי הטוב ביותר לפחות כרגע לביצוע סקרים. דרך פחות רצינית להביע את התמיכה היא להשתמש במוצר של Google ביוזמה שמנוהלת על ידי Google.
יצרתי סקר ראשוני עם שאלות לדוגמה (אפשר לגשת אליו בכתובת https://docs.google.com/forms/d/e/1FAIpQLSeBAO0UFKDZyKpg2XzRslsLJVHU61ugjc18-2PVEabTQg2_6g/viewform). מספר סביר של שאלות בגרסה הסופית הוא בין עשר ל-15. כדי לקבל תוצאות ממשיות, מומלץ להשתמש בעיקר בשאלות אמריקאיות, בסולם ליניארי ובכמה תיבות סימון. עם זאת, אסור שהסולם הלינארי יהיה דומה לכל הספקטרום (הוא רק גורם לבלבול, וסביר להניח שהתוצאות עלולות לסבול מפיזור גבוה). מומלץ להוסיף עד שתי שאלות פתוחות, אחרת התוצאות יהיו מפוזרות ולא מועילות בכלל. לדעתי, גם מספר גבוה מאוד של תשובות לא יהיה בעייתי, כי אפשר לייצא את הנתונים בקלות ולנתח אותם באופן אוטומטי באמצעות תוכנה סטטיסטית. בהנחה שמספר התשובות אכן גבוה מאוד, ניתוח השאלות הפתוחות עשוי לקחת קצת זמן, אבל אני מניח שהוא לא יהיה מכריע. אחרי הכול, סביר להניח שמשתמש ממוצע לא יכתוב סקירה על מצב המסמכים. במקרה הגרוע ביותר, אפשר פשוט לאחסן תשובות מסוימות לצורך ניתוח עתידי.
מדריכים גרפיים:
החזון שלי לגבי המדריכים הגרפיים (שמיועדים לשמש ככלי ניווט) מבוסס על הנחת יסוד נפוצה, לפיה (רוב) בני האדם טובים יותר בעיבוד מבנים חזותיים פשוטים מאשר במידע שמבוסס על טקסט בלבד. בנוסף, תרשים לפי נושאים עם קווים שמחברים בין נושאי עניין דומים הוא ללא ספק נכס חשוב מאוד למשתמשים פחות מנוסים (ולא רק).
בנוגע לפרטים של ההטמעה, אני מציע להשתמש בחבילת TikZ. קודם כול, זהו כלי רב-עוצמה ולא נראה שהוא יוצא משימוש בקרוב. בנוסף, הוא מספק פלט באיכות גבוהה, יש לו תיעוד מעולה והוא נושא שכיח ב-TeX StackExchange ובפורומים אחרים. החשוב ביותר הוא ששילוב של קובץ TikZ (ליתר דיוק, של הקישורים ההיפר-טקסט הרבים שבו) עם מסמכי תיעוד ב-HTML לא נראה כבעיה משמעותית, בגלל קיומם של חבילות ותיקונים שונים להטמעת תמונה של TikZ ב-HTML (לדוגמה, TeX4ht).
אפשר לפתור בקלות את השאלה לגבי התחזוקה העתידית של המדריכים ב-SciPy באמצעות Overleaf (כלי שמאפשר שיתוף פעולה ומציע תצוגה מקדימה מיידית) ותבניות מוגדרות מראש שאספק. באופן כללי, סביר להניח שהמדריכים הגרפיים לא יהיו שונים מאוד זה מזה. המבנה, לוח הצבעים והצורות יהיו פחות או יותר קבועים, ולכן שינוי צורת הרכיב והתאמה אישית נוספת לא יהיו בעיה.
(כדאי לבדוק את הגרסה המלאה של ההצעה – שזמינה בתיקיית GSoD המשותפת).