דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google 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). מספר סביר של שאלות בגרסה הסופית אמור להיות בין עשר לחמש עשרה. כדי לקבל תוצאות מעשיות, מומלץ להשתמש בעיקר בשאלות אמריקאיות, בקנה מידה לינארי ובכמה תיבות סימון. עם זאת, הסולם הלינארי לא אמור להיות דומה לסולם מלא (הוא רק גורם לבלבול, והתוצאות צפויות לסבול מפיזור גבוה). אמורות להיות לכל היותר שתי שאלות פתוחות, אחרת התוצאות יפוצלו מאוד ולא יועילו כלל. אני חושב שאפילו מספר גבוה מאוד של תשובות לא יהיה בעייתי עקב העובדה שניתן בקלות לייצא את הנתונים ולנתח אותם באופן אוטומטי באמצעות תוכנה סטטיסטית. בהנחה שמספר התשובות גבוה מאוד, הניתוח של שאלות פתוחות עשוי להימשך מעט זמן, אבל אני מניח שהניתוח לא יהיה מסובך. אחרי הכל, סביר להניח שמשתמש ממוצע לא יכתוב מאמר על מצב התיעוד. בתרחיש הגרוע ביותר, חלק מהתשובות יישמרו לצורך ניתוח עתידי.
קווי עזר גרפיים:
החזון שלי של המדריכים הגרפיים (שמיועדים לשמש ככלי ניווט) מבוסס על הנחה נפוצה (רוב האנשים) בעיבוד מידע חזותי פשוט יותר מאשר מידע המבוסס על טקסט בלבד. בנוסף, תרשים מוכוון-נושא עם קווים המקשרים בין תחומי עניין דומים הוא, ללא ספק, נכס בעל ערך רב עבור משתמשים פחות מנוסים (ולא רק).
בנוגע לפרטי ההטמעה, אני מציע להשתמש בחבילת TikZ. בראש ובראשונה, זהו כלי עוצמתי ונראה שהוא לא נמצא בסיכון להוצאה משימוש בקרוב. הוא גם מציע פלט באיכות גבוהה, מסמך מקיף ועדכני, ומופיעים בו לעיתים קרובות ב-TeX StackExchange ובפורומים אחרים של רשתות פופולריות. והכי חשוב, נראה שהשילוב של קובץ TikZ (ליתר דיוק, מספר ההיפר-קישורים שבו) עם תיעוד HTML לא יוצר בעיות משמעותיות בגלל הקיום של מגוון חבילות ותיקונים להטמעת תמונת TikZ ב-HTML (למשל, TeX4ht).
אפשר לפתור בקלות את שאלת התחזוקה העתידית של המדריכים ב-SciPy באמצעות שימוש, למשל, ב-Overleaf (שמאפשר שיתוף פעולה עם תצוגה מקדימה מיידית) ותבניות מוגדרות מראש שאספק. בעיקרון, לא סביר שיהיו הבדלים משמעותיים בין קווי העזר הגרפיים. המבנה, לוח הצבעים והצורות לא יהוו יותר או פחות משתנים, לכן עיצוב מחדש או התאמה אישית נוספים לא יהוו בעיה.
(ניתן לעיין בגרסה המלאה של ההצעה – זמינה בתיקיית GSoD המשותפת).