פרויקט Matplotlib

דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.

סיכום הפרויקט

ארגון הקוד הפתוח:

Matplotlib

כתב טכני:

ג'רומב

שם הפרויקט:

פיתוח נתיבי כניסה של Matplotlib

אורך הפרויקט:

אורך רגיל (3 חודשים)

תיאור הפרויקט

מבוא

ההצעה של Matplotlib לפרויקט השנה של Google Docs ב-Google Docs כוללת יצירת תוכן שיעזור להציג את Matplotlib למשתמשים חדשים. לפיתוח נתיבי כניסה של Matplotlib, אני מציע גישה חלופית לתיעוד הקיים. אני כותב/ת טכני חדש בתחום, אבל הרקע שלי הוא בתחומים שקשורים לחינוך ולחינוך. יש דמיון רב בין כתיבה טכנית וחינוך, עם התמקדות ביצירת תוכן שמברך את המשתמשים ומאפשר להם לבצע את המשימות שלהם בעזרת המשאבים שהם מעמידים לרשות המשתמשים.

בהקשר הזה, התיעוד של Matplotlib יכול לשפר את יכולת ההזדהות עם משתמשים חדשים. חלק גדול מהחומרים הקיימים כיום מורכב מנתונים אקראיים ומרכיבים חזותיים ללא תוויות. תמונות כאלה מצוינות להצגה מהירה של הרכיבים החזותיים ושל התכונות של Matplotlib. עם זאת, בתרחיש לדוגמה של מישהו חדש ב-Matplotlib, קשה לבחון טרנספורמציה של נתונים ברכיבים חזותיים.

הקשר בגישה חושית הוא פתרון למכשול הזה. בכתיבת הליך מבחינת דוגמה מהעולם האמיתי, אנחנו מפגינים הבנה של הסביבה שבה המשתמש פועל. כך ניתן לשפר את הקשר בין התיעוד למשתמש מבחינת עמידה ביעד או הציפייה בביצוע משימה.

למשתמש יש מטרה נגזרת עקבית. לדוגמה, מדעני נתונים בחברת נעליים חייב להציג נתוני לקוחות לצוות כדי להמחיש מגמות בקניות לאורך זמן. במצב כזה, המשתמש צריך ללמוד לנווט ב-Maplotlib ולנצל את הכלים שבספרייה כדי להשלים את המשימה.

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

כשמשתמשים נתקלים בבעיות, בדרך כלל הם משתמשים בחיפוש כדי לפתור אותן. במקום להסתמך על החיפוש כשיטה העיקרית לניווט, הקצאת המשתמשים יכולה ליצור תוכנית לימודים משלהם מתוך התיעוד. כלומר, משתמש מחפש פתרון לבעיה שלו. אם הוא ייתקל בבעיה אחרת או ירצה מידע נוסף, הוא ישתמש בקישורים מוטמעים ויסודיים לאורך כל התהליך.

דבר זה יכלול ארכיטקטורה מלמטה למעלה במערכת הארגונית. רשת עשירה של קישורים לנושאים בעלי עניין משותף ונושאים אינפורמטיביים לכל נושא יכולה לעזור לך לבנות רשת חזקה. המשתמשים ברשת הזו נוטים להמשיך להשתמש בתיעוד כאשר הוא מנווט לנושא שלו ומחפש עוד ועוד מידע הקשור לאותו נושא.

מכשולים

תמיד יש אתגרים בפרויקט כמה שיותר מקיף ומפורט מהסוג הזה. ככותב טכני חדש בתחום, יש לי ניסיון מוגבל בשימוש ב-Sphinx וב-ReST לכתיבת מסמכים. בכל מה שנוגע ל-Maplotlib ול-Git, אני רק בתחילת הדרך. נדרש זמן כדי להתמודד עם ארבע המערכות האלה ולהתרגל להשתמש בהן לצורך שיתוף פעולה ומחקר. אצטרך להאציל זמן במהלך שלב הקישור לקהילה ועוד מוקדם יותר כדי לבנות את הבסיס ההכרחי לנתיבים ברמות הכניסה. במהלך התקופה הזו, אם נתקלתי בבעיות שקשורות למושגים וליסודות, אצטרך לפנות לקהילה לקבלת תמיכה נוספת.

תיאום מאמצי שיתוף פעולה בין אזורי זמן שונים ובין פלטפורמות באינטרנט יידרש גם הוא להתאמה. אנשים בכל הענף משתמשים במגוון ערוצי תקשורת, לכן צריך לוודא שאני נגיש ונגיש בכל התחומים. אני אנהל בשקיפות את סדר העדיפויות שלי לגבי ציפיות שונות לאורך התהליך. אני רק בתחילת הדרך שלי, במטרה לעבוד עם תוכן כזה בתחום, אבל משקיעים בשמירה על האחריות ועל הפתיחות לקבלת משוב וביקורת. לדעתי התכונות האלה חשובות בכל תחום.

בנוסף, הגדלת הבדיקות של נוחות השימוש היא קטע תיעוד שיכול להועיל לנתיבי הכניסה של Matplotlib. עריכת סקרים לגבי נוחות השימוש בתוכן משמשת לספק פרופיל של משתמש, כלומר פרסונות. למידע כמו חוויית המשתמש, התחום שבו הוא עוסק והיסטוריית פתרון הבעיות הוא בעל ערך. החלקים האלה עוזרים ליצור את השפה שמאחורי ההליך. כשכותבים פוגש את הקוראים ברמה שלהם, התוכן מתבגר מעבר לתפקיד של הוראה בלבד.

לרוב אתגרים גדולים קורים בתהליך מתמשך של בדיקת נוחות השימוש. לעיתים קרובות מדי, במהלך פיתוח התוכן, תתבצע בדיקה יחידה, אם בכלל. בדיקות סדירות של נוחות השימוש עוזרות לפתח את הנרטיב של התוכן. אני מקווה להגדיר לוח זמנים או לערוך בדיקות חוזרות של נוחות השימוש בקהילת Matplotlib.

סיכום

בזמני הפנוי יש לי מעט ניסיון בשימוש ב-Python וב-Matplotlib. הכמות שלמדתי בעצמי בחודשים האחרונים ונתמכת על ידי המסמכים הנוכחיים וסקרנותי האישית. היו גם כמה סרטונים ומנטורים שהיו לי בתקופה הזו. יש לי עדיין הרבה מה ללמוד ויש לי עוד מקום לשיפור בזמן יצירת תוכנית לימודים משלי בנושא תכנות שמעניינת אותי.

אחרי שראיתי את הרעיונות של מטפלוטליב והקהילה ל-GSoD, אני מרגישה שזו תהיה חוויה מצוינת בצמיחה לשיפור הכישורים שלי ככותב/ת טכני, ולקבל הזדמנות ללמוד עוד מהאנשים שמאחורי הקלעים. הרגשתי שפרויקט מטפלוטליב הוא בעל משמעות וגם משהו שאני אוהב באידיאולוגיה.

במסגרת העבודה על עדכון במדריך השימוש, המטרה שלי ככותבת טכנית היא לעזור למשתמשים לבצע את המשימות הרצויות מבלי להציף את התכונות הזמינות. לדעתי התיעוד הטוב ביותר ימשיך לגדול ולהסתגל למשתמשים ויאפשר לכל משתמש לנווט לפתרונות שלו.