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