בדף הזה מופיעים הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Docs ל-Google Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- Matplotlib
- כותבים טכניים:
- jeromev
- שם הפרויקט:
- פיתוח נתיבי כניסה של Matplotlib
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
מבוא
ההצעה של Matplotlib לפרויקט במסגרת Google Season of Docs השנה היא ליצור תוכן שיעזור להציג את Matplotlib למשתמשים חדשים. לצורך פיתוח נתיבי כניסה של Matplotlib, אני מציע גישה חלופית לזו שמופיעה במסמכי העזרה הנוכחיים. אני כותב טכני חדש בתחום, אבל הרקע שלי הוא בחינוך ובתחומים שקשורים לחינוך. לכתיבה טכנית ולחינוך יש קווים מקבילים סביב יצירת תוכן שמעורר הבנה כלפי המשתמשים ומאפשר להם לבצע את המשימות שלהם בעזרת המשאבים שעומדים לרשות המשתמשים.
בהקשר הזה, כדאי לשפר את המסמכים של Matplotlib כדי להקל על המשתמשים החדשים. כרגע, רוב החומר מורכב מנתונים אקראיים ומחומרים חזותיים ללא תוויות. אלה מעולה להצגה מהירה של הרכיבים החזותיים והתכונות של Matplotlib. עם זאת, בתרחיש לדוגמה של Matplotlib, קשה לעבור בין נתונים לרכיבים חזותיים.
הוספת הקשר לגישה להסבר היא פתרון לבעיה הזו. כשיוצרים נוהל תוך התמקדות בדוגמה מהעולם האמיתי, אפשר להראות הבנה של הסביבה שבה המשתמש עובד. זה משפר את הקשר בין התיעוד לבין המשתמש מבחינת הגעה ליעד או ציפייה לביצוע משימה.
למשתמש יש מטרה משנית עקבית. לדוגמה, מדען נתונים בחברת נעליים צריך להציג נתוני לקוחות לצוות כדי להמחיש מגמות קנייה לאורך זמן. במצב כזה, המשתמש צריך ללמוד לנווט ב-Matplotlib ולהשתמש בכלים בספרייה כדי להשלים את המשימה.
הוספת הקשר נוסף למסמכים התומכים יכולה לעזור למשתמש חדש להבין את הנושא. המטרה המשוערת של המשתמש תואמת למסמכי התיעוד. אני מקווה לעבוד לקראת החזון שדיבר עליו המפתח הראשי טום קאסול (Tom Caswell) בראיון ב-2017: "כדי שיהיה מישהו שיכול לכתוב ויש לו אמפתיה למשתמשים, שיעבור על הנושא ויכתוב בעצם ספר של 200 עמודים בשם 'מבוא ל-Matplotlib', וזה יהיה הכניסה הראשית למסמכים".
גישה חלופית לכתיבה חשיפה
במסמכי העזרה הנוכחיים מפורטות התכונות של Matplotlib, כלומר הפעולות שמשתמש יכול לבצע באמצעות הספרייה. לדוגמה, הדרכה לעיתים קרובות עוקבת אחרי דפוס שלא כולל הסבר על השיטה הבסיסית.
{what the method does} -> {parameters} -> {returns} -> {related links} -> {examples}
לרוב, במסמכי תיעוד ובתמיכה בנושאי תכנות, מומלץ למשתמש להריץ את הקוד בעצמו כדי להבין מה קורה. דפוס חשיבה של תכנות משפר את הבנת הנושא של משתמש, אבל עקומת הלמידה של הטרנספורמציות כוללת מעט תוכן תומך. זו יכולה להיות משימה מאתגרת מאוד כי התיעוד מוגבל.
הוספה של תרשימים, תמונות או רכיבים חזותיים אחרים תעזור ליצור הזדמנויות למידה חדשות. המבנה שלמטה יכול לשמש גם כתבנית לתוכן חדש. בנוסף, אם מוסיפים תמונות או גרפיקה ללא טקסט, כדאי להשתמש בתכונות כמו תוספי יתרונות מרכזיים וסימני הדרכה. לפעמים קשה יותר לנווט בתמונות בלי אינדיקציות לאופן שבו הקוד הופך לפלט שבוצע או למיקום שבו הוא הופך לפלט. לדעתי חסר רכיב חזותי משמעותי שיכול לעזור להבין טוב יותר את הנושאים.
{method explanation} -> {expository use case/scenario} -> {sample code} -> {parameters} -> {returns} -> {additional examples} -> {informational topic/subject affinity links}
יש פוטנציאל עצום בגישה החלופית הזו של שימוש בכתיבה מסבירת לצורך תיעוד. כשמשתמשים רואים מגוון רחב של מושגים של טרנספורמציות, הם יכולים לזהות טוב יותר את האסטרטגיות הבסיסיות לפיתוח חזותיות לנתונים. הידע הזה יכול לעזור למשתמשים לחדש ולנצל את התכונות בעזרת דוגמאות שמבוססות על תרחישים מציאותיים.
ככל ש-Matplotlib צוברת פופולריות, העקביות בקלות השימוש ובנגישות היא עדות למוניטין של הספרייה. המאפיינים האלה מאפשרים להציג דפוסים ואסטרטגיות נפוצות שיכולים להופיע לא רק בקוד, אלא גם במסמכי העזרה. Matplotlib היא ספרייה פשוטה וסטנדרטית לתכנות, כפי שמעידים השימוש ההולך וגדל בה והמשאבים המתרחבים שלה. היא יכולה להיות כזו גם לצורך תיעוד טכני.
כשמשתמשים נתקלים בבעיות, מקובל להשתמש בחיפוש כדי לפתור אותן. במקום להסתמך על חיפוש כשיטה הראשית לניווט, מומלץ לאפשר למשתמשים ליצור תוכנית לימודים משלהם בתוך המסמכים. במובן הזה, משתמש מחפש פתרון לבעיה שלו, ואז כשהוא נתקל בבעיה אחרת או רוצה לקבל מידע נוסף, הוא משתמש בקישורים מוטמעים ומפורטים לאורך כל הדרך.
המשמעות היא ארכיטקטורה מלמטה למעלה במערכת הארגונית. רשת עשירה של קישורים לתחומי עניין משותפים ונושאי מידע תעזור ליצור רשת איכותית לכל נושא ב-Matplotlib. ברשת הזו, סביר יותר שמשתמש ימשיך להשתמש במסמכי העזרה בזמן שהוא מנווט לנושא שלו ומגלה מידע נוסף נוסף שקשור לנושא הזה.
מכשולים
בפרויקט תמיד יש אתגרים מקיפים ומפורטים כמו זה. אני כותב טכני חדש בתחום, ולכן יש לי ניסיון מוגבל בשימוש ב-Sphinx וב-ReST לכתיבת מסמכי עזר. אני גם מתחיל ב-Matplotlib וב-Git. ייקח זמן להבין את ארבע המערכות האלה ולהשתמש בהן לשיתוף פעולה ולמחקר. אצטרך להקצות זמן במהלך שלב יצירת הקשרים בקהילה, וגם לפני כן, כדי ליצור את הבסיס הנדרש למסלולים ברמת הכניסה. במהלך התקופה הזו, אם יהיו לי בעיות עם מושגים ותובנות בסיסיות, אצטרך לפנות לקהילה לקבלת תמיכה נוספת.
גם תיאום המאמצים המשותפים בין אזורי זמן שונים ופלטפורמות אונליין ידרוש הסתגלות מסוימת. יש מגוון דרכים לתקשורת שבהן אנשים בכל רחבי התעשייה משתמשים, ולכן חשוב לי לוודא שאני נגיש ונוח ליצירת קשר בכל אמצעי. לאורך התהליך אהיה שקוף לגבי סדר העדיפויות שלי בטיפול בבקשות השונות. זו רק ההתחלה שלי בעבודה כזו בתחום, אבל אני מחויבת לנהוג באחריות ולהיות פתוחה למשוב ולביקורת. לדעתי, התכונות האלה חשובות בכל תחום.
בנוסף, הרחבת בדיקות נוחות השימוש היא קטע במסמכי התיעוד שלדעתי יעזור לנתיבים של Matplotlib. מטרת הסקרים לגבי נוחות השימוש בתוכן היא לספק פרופיל של משתמש, כלומר דמויות משתמשים. יש בו מידע חשוב כמו חוויית המשתמש, הענף שלו והיסטוריית פתרון הבעיות. הרכיבים האלה עוזרים ליצור את השפה שמאחורי התהליך. כשהכתיבה מתאימה לקוראים ברמה שלהם, התוכן הופך למשהו יותר מרק חינוכי.
לרוב, הבעיה הגדולה היא ליצור תהליך שוטף של בדיקות נוחות השימוש. במהלך פיתוח התוכן, קיים הרבה יותר מדי מקרים של מופע אחד של בדיקה, אם בכלל. בדיקות שימושיות שוטפות עוזרות לשפר את העלילה של התוכן. אני מקווה להגדיר לוח זמנים או לערוך בדיקות חוזרות של שימושיות בעזרת קהילת Matplotlib.
סיכום
יש לי ניסיון קטן בשימוש ב-Python וב-Matplotlib בשעות הפנאי. הידע שרכשתי בחודשים האחרונים הגיע בעזרת המסמכים העדכניים וסקרנותי. בנוסף, צפיתי בכמה סרטונים ועזרתי לי כמה מנטורים. יש לי עוד הרבה מה ללמוד והרבה יותר עוד מקום לשיפור, בזמן שאני יוצרת את תוכנית הלימודים שלי של תכנות שמעניינות אותי.
אחרי שראיתי את הרעיונות של Matplotlib והקהילה ל-GSoD, נראה לי שזו תהיה הזדמנות מצוינת לשפר את היכולות שלי ככותב טכני ולקבל הזדמנות ללמוד יותר מהאנשים שמאחורי הקלעים. הפרויקט הזה של Matplotlib הוא משמעותי בעיני, וגם משהו שאני מתלהב ממנו מבחינה אידיאולוגית.
ככותבת טכנית, המטרה שלי בעבודה על שידרוג מדריך השימוש היא לעזור למשתמשים להשלים את המשימות שהם רוצים לבצע בלי להרגיש מוצפים מהתכונות הזמינות. לדעתי, מסמכי התיעוד הטובים ביותר ימשיכו להתפתח ולהתאים את עצמם למשתמשים, ויאפשרו לכל משתמש לנווט לפתרונות משלו.