פרויקט NumPy

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

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

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

NumPy

כותבים טכניים:

cooperrc

שם הפרויקט:

מסמכי העזרה של NumPy לצורך הדרכה של הקהילה

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

אורך סטנדרטי (3 חודשים)

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

מבוא

NumPy מספקת חישוב מבוסס-מערך מהיר ונקי בספריית תוכנה חינמית בקוד פתוח. זוהי חבילת יסוד ב-SciPy stack למחשוב מדעי [1]. יותר מ-370 אלף פרויקטים משתמשים במחשוב מחשוב יעיל [2]. משתמשי NumPy מקבלים אתר חדש עם אפליקציות ומקרים לדוגמה [1]. כשמשתמש חדש מוצא את דף המסמכים, הוא נתקל בכמה קישורים מסוג 'כאן מתחילים' ומדריכים מבואיים שיכולים להיות מרתקים למתחילים, כמו 'יסודות NumPy' או 'החלפת בייטים'. התחלתי להשתמש ב-NumPy לפני עשר שנים במהלך לימודי התואר השני. מצאתי את עצמי מחברים פוסטים בבלוגים, סיכומי הרצאות ותשובות של StackExchange כדי לא לעבור על מסמכי התיעוד של NumPy. נכון לעכשיו יש יותר מ-360 אלף שיחות ב-StackExchange שעוסקות ב-NumPy. אני מניח שמשתמשים אחרים עברו דרכים דומות להצלחה ב-NumPy. אבני הבניין של הכלים החינוכיים הם תקשורת וקהילה [4]. המסמכים צריכים ליצור קהילה שמשקפת את היעדים הרצויים של הפרויקט. המסמכים צריכים להיות מדריך עקבי וברור למשתמש חדש. המדריכים אמורים לספק למשתמשים חדשים שלבים קלים לביצוע וליצור נוחות בעזרת הספרייה [3]. המסמכים צריכים לקבל משתמשים חדשים לקהילה של NumPy. המבנה, הקצב והמחברים של המסמכים צריכים ליצור מקום שמעודד חקירה ותקשורת. ההצעה הזו תארגן ותשלים את הפערים במסמכי התיעוד הנוכחיים של NumPy כדי שמשתמשים חדשים יתקבלו בברכה לקהילה.

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

ג'ון דיואי אמר שהבסיס של הלמידה הוא חוויה אמיתית [4]. לקהילת NumPy יש כמות עצומה של ניסיון אמיתי שאפשר לשתף עם משתמשים אחרים. חינוך מבוסס על קהילה ותקשורת. דף מסמכי עזרה מאורגן מאפשר למשתמשים חדשים להכיר את NumPy. בנוסף, הכלי יוצר תבנית מובנית לאנשים שרוצים לתרום ל-NumPy כדי שיוכלו לשתף את החוויות שלהם.

יש ארבעה מרחבים משותפים רחבים לתיעוד תוכנה [3]: מרחב הדרכה, מרחב הוראות, מרחב הסברים ומרחב עזר. במסמכי העזרה של NumPy יש כמה מסמכים במרחב הדרכה שמכילים הסברים ומדריכים. המרחב של המדריך צריך להתמקד בהדרכת המשתמשים, ולהשתמש בשלבים שקל לחזור עליהם כדי להעביר רעיונות. מרחב הביצוע כולל יותר תהליכים מוכווני מטרה שמשתמשים יכולים ליישם באפליקציות בעולם האמיתי. במרחב ההסבר מוצג מידע מפורט על מחרוזות מסמכים (doc-strings) בכל פונקציה. המרחבים הנוכחיים של המדריכים וההדרכות לא מוגדרים בבירור ולפעמים הם נכנסים למרחב של ההסברים והמקורות. יש מדריך מעולה למתחילים, ויש גם מקור מידע מצוין למשתמשי Matlab ליצירת קוד NumPy במאמר 'Numpy למשתמשי Matlab'. ההגדרה הברורה של ארבעת המרחבים האלה מאפשרת להבין את המסמכים בצורה טובה יותר.

פער במאגר הידע/צורך שלא טופל

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

ההסבר

ההצעה הזו לקיץ של Google Docs חשובה לי וליעדים הפדגוגיים והקריירה שלי. אני משתמשת ב-NumPy וב-SciPy בכל הקורסים שלי. לתלמידים שלי קשה לנווט במסמכי העזרה הנוכחיים. אני רוצה להשתמש בניסיון שלי בהוראת תכנות לסטודנטים שלא למדו מדעי המחשב כדי לעזור בארגון, בעריכה ובמילוי הפערים במדריכים הנוכחיים. לאחר מכן אוכל להשתמש במסמכי התיעוד כחומר לימודי וכחומר עזר בקורסים שלי. יצרתי עשרות מדריכים, תרגילים ודוגמאות באמצעות Python ו-. אני רוצה להמיר חלק מהחומר הזה למדריכים ולהוראות. יותר מ-800 תלמידים השתמשו ב-NumPy (כחלק מסטאק Scipy) ויש לי כמה תלמידים שרוצים להיות שותפים ביצירת תיעוד לסמסטר הסתיו. אני מלמדת במחלקה למהנדסה מכנית באוניברסיטת קונטיקט כבר 4 שנים, והעברתי יותר מ-30 שעות לימוד בקורסים.

מטרות ספציפיות

יש לי שלוש מטרות ספציפיות להצעה הזו של Google לקיץ של Google Docs: 1. ארגון המסמכים הקיימים, 2. עורכים את המדריכים הקיימים (מדריך למתחילים, יצירת מערך, הוספת אינדקס, אלגברה לינארית ו-NumPy ל-Matlab) כדי להעביר את פרטי העזרה למרחב ההסבר, וגם: 3. ליצור חומרי הדרכה עם התלמידים. לכל מטרה ספציפית יש תוצאה צפויה לגבי ההצעה.

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

התוצאות הצפויות הן: 1. דף מסמכי עזרה שעבר שינוי, שבו יש הפרדה ברורה בין ארבעת המרחבים: מדריכים, מדריכים למתחילים, הסברים ומקורות מידע. 2.מדריכים חדשים בנושאים הבאים: קריאה וכתיבה של מערכי נתונים, יצירה של מערכי נתונים (np.zeros,‏ np.ones,‏ np.block וכו') ופעולות אלגברה ליניארית לעומת פעולות לפי רכיבים ב-NumPy. 3. מרחב של מדריכים למתחילים שנבחרו בקפידה.

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

שותפים חדשים ליצירת מסמכי עזרה יכולים לתרום תרחישי שימוש קטנים למיליוני משתמשים בלי ליצור את כל מסמכי העזרה של Sphinx. אנחנו רוצים להמשיך לבנות את קהילת ההוראה והלמידה שלנו. המסמכים המוצעים יהיו דומים למסמכים הקיימים של קוד פתוח, כמו Matplotlib, ‏ Divio וכו'. משתמשים חדשים ושותפים פוטנציאליים יוכלו ללמוד בקלות רבה יותר איך להשתמש ב-NumPy בתחומים ובתוכנות שלהם.

לוח הזמנים לפרויקט הוא 14/9-11/30. השלב הראשון הוא ליצור את המסמכים ולפריד את התוכן במדריכים הנוכחיים לתוכן של מדריכים, הוראות והסברים. זה יקרה בחמשת השבועות הראשונים של הפרויקט כחלק מתיקון התוצאות 1 ו-2, בהתאמה. המבנה המוצע של מסמכי העזרה מוצג בקטע 'הצעה למסמכי עזרה' בהמשך.

המסמכים המוצעים:

i.Tutorials:

• יסודות מוחלטים למתחילים (הסרת ההתקנה, האם ניתן להחליף ייבוא/ייצוא של pandas ב-numpy.loadtxt?)
• קישור ל'מה זה numpy'
• קישור להוראות התקנה בסיסיות
• מדריך למתחילים (מיועד להמשך המדריך ל-Python)
• עבודה עם מערכים של NumPy
• יצירת מערך (np.zeros,‏ np.ones,‏ np.block וכו') (write: med-low priority)
• פעולות לפי רכיבים (+,-,*,/) ופעולות של אלגברה לינארית (+,-,@, linalg.solve) (write:med priority)
• קריאה וכתיבה של נתונים באמצעות Numpy (כתיבה: עדיפות גבוהה)
• הוספה לאינדקס

ii. מדריכים:

• אלגברה לינארית במערכים n-ממדיים (אשמח לערוך את הכותרות והתיאורים, ואולי לשנות את הכותרת ל'עיבוד תמונות באמצעות אלגברה לינארית של Numpy')
• קישור לתוכן הדרכה של numpy-tutorials (עבודה מתמשכת)

iii. הסבר:

• סוגי נתונים
• קלט/פלט באמצעות Numpy
• הוספה לאינדקס
• שידור
• החלפת בייטים
• מערכים מובְנים
• כתיבת מאגרי מערכי נתונים בהתאמה אישית
• יצירת מחלקה משנית של ndarray
• שונות

iv. מרחב העזר:

• מילון מונחים
• Numpy API Reference
• Numpy למשתמשי Matlab (טבלת השקיפות היא טבלת עזר נהדרת, אבל הדיון על מערך/מטריצה מסיחת דעת ונראה שהיא לא בשימוש)

בסיום העונה של Google Docs, אני מציע את התוצאות הבאות:

• דף אינטרנט מתוקן של מסמכי תיעוד שמפריד באופן ברור בין ארבעת המרחבים: מדריכים, הדרכה, הסבר וחומר עזר
• מדריכים חדשים בנושאים הבאים: יצירת מערך (np.zeros,‏ np.ones,‏ np.block וכו'), פעולות על רכיבים (+,-,*,/) ופעולות של אלגברה לינארית (+,-,@,‏ linalg.solve), קריאה וכתיבה של נתונים באמצעות Numpy (עדיפות גבוהה)
• המלצה על מסמכי הדרכה כדי להגדיל את מספר התכנים שהמשתמשים מוסיפים ולקדם את מטרות הקהילה בתחום ההוראה והלמידה

לכל תוצאה יש מספר שלבים שמפורטים בטבלאות שלמטה לגבי התוצאות 1-3. בזמן שמסמכי התיעוד המוצעים מוצעים לבדיקה, המדריך "מערכי קריאה/כתיבה" בעדיפות גבוהה ייכתב לצורך שליחה כבקשת משיכה כחלק מתוצאה 2. במהלך הבדיקה של האתר המתוקן והמדריך המעודכן בנושא 'קריאה/כתיבה של מערכי נתונים', אתחיל לכתוב מדריך ליצירת מערכי נתונים באמצעות פונקציות NumPy, למשל np.ones,‏ np.zeros,‏ np.diag. הזמן שנותר ישמש לתשובה על בעיות בבקשות משיכה (pull request) ולהתחיל לכתוב את המדריך ברמה 3: פעולות אלגברה לינארית ופעולות לפי רכיבים ב-Python.

התוצאה השלישית היא לייעץ לתלמידים באוניברסיטת קונטיקט ליצור מסמכי עזרה במאגר numpy-tutorials. המדריכים או מסמכי ההדרכה שיישלחו יהיו מחברות של Jupyter שמבוססות על NumPy כדי לפתור בעיות הנדסיות. אשתמש בחלק מההערות או מהדוגמאות שלי מהקורס כדי לשלוח ספר לימוד לדוגמה. אשלח לתלמידים המלצה לפעול לפי הפריסה והמבנה בזמן שנבנה תבנית ותוכנית עיצוב. התוצאה הזו מספקת לתלמידים חוויה אמיתית של העברת מושגים ופתרונות לקהל רחב יותר. זו הזדמנות מצוינת לסטודנטים להשתתף בקהילה של NumPy וללמוד.

תוצאה 1: תאריך ניתן למסירה של האתר מאגר עיבוד ובניית מסמכי Docs עם Sphinx 21/9 בניית דף אינטרנט עם ארבעה מרחבים מוגדרים ומקושרים 10/1 העברת מדריכים נוכחיים למרחבים מתאימים ומסמכי בניית מסמכי 10/10 שליחת PR אל github עם השינויים המוצעים 11/1 מענה על הערות/הצעות10 ותיקון קבוע

תוצאה 2: עדכון של מדריכים מועד הגשה: בדיקת דירוג העריכה של המדריכים 21/9 הפרדת תוכן המדריך הנוכחי למרחבים Tutorial ו-Explanation 1/10 כתיבה של דירוג 1: מערכי קריאה/כתיבה 10/10 שליחת בקשת תיקון (PR) ל-GitHub לצורך הפרדה ועדכון 20/10 כתיבה של דירוג 2: בקשת תיקון (PR) ליצירת מערך 15/11 כתיבה של דירוג 3: פעולות אלגברה לינארית ומבוססות-רכיבים בקשת תיקון (PR) 30/11

ההצעה שלנו לגבי דירוג הגרסאות של ההדרכות (היא עשויה להשתנות בהתאם למנטורים או לקהילה):

1. דף ריק כרגע של מערכי קריאה/כתיבה

2. יצירת מערך (np.zeros,‏ np.ones,‏ np.block וכו') לא קיים: כדאי להסביר ולדגים למשתמשים חדשים את הכלים הנפוצים ליצירה ולפעולה של מערכי נתונים

3. פעולות אלגברה ליניארית ופעולות על רכיבים (+,-,*,/ ו-+,-@,linalg.solve) לא קיימות: האפשרות הזו שימושית במיוחד עבור 1. משתמשי Matlab ו-2. אנשים שמשתמשים באלגברה לינארית (למידת מכונה, רגרסיה לינארית וכו')

תוצאה 3: תאריך קיים להדרכה עם תאריך שליחה קישור חיצוני(בעיה/דוגמה) בניית דוגמה להדרכה (מועמד: איך למצוא תדרים טבעיים של מיתרי גיטרה 10/20
בניית תבנית הדרכה לתורמים חדשים 10/1 בתהליך יצירת תבנית של מדריך בנושא יחסי ציבור ומפריים: עבודה עם חברי קהילה אחרים עם סטטוס הדרכה וצירוף תלמידים אחרים לקבלת סטטוסי הדרכה חדשים והכנת מחברים אחרים לקבלת סטטוס 'מדריכים'

המשמעות הצפויה

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

קובצי עזר

1. גישה לאתר NumPy.org ב-07/2020.
2. מאגר NumPy ב-GitHub.
3. מערכת התיעוד. Divio.com נכנסו אליו ביולי 2020.
4. דיואי, ג'ון. דמוקרטיה וחינוך. Project Gutenberg, אוגוסט 2015.
5. Dewey, John. Quest for Certainty George Allen And Unwin Limited. 06/2005.