דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- NumPy
- כתב טכני:
- קופר
- שם הפרויקט:
- מסמכי תיעוד מספריים לחינוך קהילתי
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
מבוא
NumPy מספק מחשוב נקי ומהיר מבוסס-מערך בספריית תוכנות בקוד פתוח ללא תשלום. זוהי חבילה בסיסית בסטאק SciPy למחשוב מדעי [1]. יותר מ-370 אלף פרויקטים משתמשים במחשוב מערכים יעיל [2]. משתמשי NumPy מקבלים את פני אתר חדש עם יישומים ומקרים לדוגמה [1]. כשמשתמשים חדשים מוצאים את דף התיעוד, הם נתקלים בכמה קישורי "Start here" ומדריכי מבוא שיכולים להיראות כמו NumPy Basics/byte-swaping. התחלתי להשתמש ב-NumPy לפני עשר שנים בבית הספר המקצועי. מצאתי את עצמי כותב פוסטים בבלוגים, הערות להרצאות ותשובות של StackExchange כדי להימנע מעיון במסמכי התיעוד של NumPy. כרגע קיימות יותר מ-360 אלף שיחות ב-StackExchange שקשורות ל-NumPy. אני מניח שמשתמשים אחרים חוו דרכים דומות להצלחה ב-NumPy. אבני הבניין של כלים חינוכיים הם תקשורת וקהילה [4]. התיעוד צריך ליצור קהילה שמשקפת את המטרות הרצויות של הפרויקט. התיעוד צריך להיות מדריך עקבי וברור למשתמש חדש. המדריכים צריכים לספק למשתמשים חדשים שלבים קלים לביצוע, וליצור חוויית משתמש נוחה בעזרת הספרייה [3]. התיעוד אמור לברך משתמש חדש שיצטרף לקהילת NumPy. המבנה, הקצב ומחברי המסמכים צריכים ליצור מקום שמעודד חקירה ותקשורת. הצעה זו תארגן ותמלא פערים בתיעוד ה-NumPy הנוכחי, כדי שמשתמשים חדשים יקבלו את המידע הנדרש ויקבלו את ההצטרפות לקהילה.
את הידע שהמשתמשים מתקשרים איתם מתקבלות מבדיקות וניסויים [4,5]. הידע תלוי בשיטת הבדיקה וההערכה. תוכן שמספק מטרות וכלים ברורים במדריכים מאפשר למשתמשים לבחון רעיונות ושיטות חדשות ולהעריך אותן. הקהילה יכולה לבנות מאגר ידע כדי לשפר מיומנויות, עובדות ואפליקציות. למרחב ההדרכה יש יתרון כפול. ראשית, למשתמשים חדשים ומנוסים יש להגדיר יעדים ברורים לבדיקה ולבנייה של ניסויים. שנית, אנשים שיוצרים תיעוד אפשרי מקבלים מקום שבו הם יכולים להציג את היעדים, השיטות והפתרונות שלהם. סביבת ההדרכה ממלאת צורך מיידי בהפיכת המסמכים של NumPy לנגישים יותר למשתמשים חדשים ולתורמים אפשריים. ידע נוכחי
ג'ון דיואי אמר שבסיס הלמידה הוא חוויה אמיתית [4]. לקהילת NumPy יש כמות עצומה של ניסיון אמיתי שאפשר לשתף עם משתמשים אחרים. החינוך מושתת על קהילה ותקשורת. דף תיעוד מאורגן מאפשר למשתמשים חדשים ליהנות מ-NumPy. היא גם יוצרת תבנית מובנית לתורמים פוטנציאליים שבעזרתם יוכלו להעביר חוויות ב-NumPy.
יש ארבעה אזורים המקובצים באופן נרחב לתיעוד תוכנה [3]: מרחב הדרכה, מרחב הדרכה, מרחב הסברים ומקום לעיון. התיעוד של NumPy כולל מספר מסמכים בתחום מערך השיעור, שמשלבים הסברים ותוכן של הוראות כיצד למקם במדריך. מרחב ההדרכה צריך להתמקד בהדרכת המשתמש ולהשתמש בשלבים קלים לשימוש חוזר כדי להעביר את הרעיונות שלכם. סביבת ההדרכה מספקת הליכים ממוקדים יותר במטרה, שמשתמשים יכולים ליישם באפליקציות בעולם האמיתי. במרחב ההסבר ניתן למצוא מידע מפורט על מחרוזות מסמכים מפורטות בכל פונקציה. מערך השיעור ומרחבי ההדרכה הנוכחיים אינם מסומנים בצורה ברורה, ולפעמים הם נכנסים לשטח ההסבר וההפניה. יש באתר מדריך מצוין של 'מתחילת אבסולוטית', ויש גם חומר עזר מצוין למשתמשי Matlab לבניית קוד NumPy בתוך 'Numpy for Matlab'. הפרדה ברורה בין ארבעת השטחים האלה תבהיר את התיעוד.
פער במאגר הידע/צורך לא מנוצל
התיעוד הנוכחי עוסק בנושאים נדרשים רבים, אך אין הבחנה ברורה בין מרחבי הדרכה, הוראות ביצוע, הסברים והפניות. התוצאה היא בלבול אצל תורמים פוטנציאליים. הסברים וחומרי עזר בקטע המדריך עשויים להציף משתמשים חדשים, וכמות גדולה של משתתפים מתמודדים עם מכשולים בביצוע תורמים. אני מציע פריסה נגישה יותר למשתמשים חדשים ולתורמי מסמכים אפשריים, עם זרימה לוגית בתיעוד וניהול בקשות משיכה למסמכי הדרכה שמשתמשים חדשים מוסיפים. המטרה שלי לטווח הארוך היא לבנות את קהילת התיעוד כך שהלמידה מהתיעוד תהיה חוויה של 'תן וקח' של למידה ותקשורת. מודל התיעוד הזה יחזק את החינוך בחוויה בפועל של יוצרים חדשים ותורמים פוטנציאליים.
פירוט הנימוקים
ההצעה לקיץ של Google Docs חשובה לי למטרות הפדגוגיות והקריירה שלי. אני משתמשת ב-NumPy וב-SciPy בכל הקורסים שלי. לתלמידים שלי קשה לנווט בתיעוד הנוכחי. אני רוצה להשתמש בניסיון שלי ללמד מורות ומורים שאינם מומחים במדעי המחשב איך לתכנת כדי לארגן, לערוך ולמלא פערים במדריכים הנוכחיים. אחרי זה אוכל להשתמש בתיעוד כספר לימוד וכחומר עזר עבור הקורסים שלי. יצרתי עשרות מדריכים, תרגילים ודוגמאות באמצעות Python ו-
מטרות ספציפיות
יש לי שלוש מטרות ספציפיות להצעה הזו של Google Summer of Docs: 1. מסדרים את המסמכים הנוכחיים, 2. ערכו את המדריכים הנוכחיים (המדריך למתחילים, יצירת מערך, הוספה לאינדקס, אלגברה לינארית ו-NumPy ל-Matlab) כדי להעביר את פרטי ההפניה למרחב ההסבר, ו-3. להכין חומרי הדרכה לתלמידים. לכל מטרה ספציפית יש תוצאה צפויה לגבי ההצעה.
מטרת שלוש המטרות הספציפיות האלה היא ליצור תיעוד נעים יותר למשתמשים חדשים ולספק מבנה לתורמים פוטנציאליים. המטרות גם עוזרות לקדם את היעד לטווח הארוך של הרחבת קהילת התיעוד של NumPy. תוצאות צפויות
יש לי שלוש תוצאות צפויות: 1. דף אינטרנט מתוקן של תיעוד שמפריד בבירור בין ארבעת הרווחים: מדריכים, הדרכות, הסברים והפניות, 2. מדריכים חדשים עבור: מערכים לקריאה ולכתיבה, יצירת מערכים (np.zeros , np.ones , np.block וכו') ופעולת אלגברה ברמת הרכיבים לעומת פעולה באלגברה לינארית ב-NumPy, ו-3. מרחב הדרכה שנאסף בנושא.
התוצאות הצפויות האלה יעזרו למשתמשים חדשים להתקדם במסמכים, לספק למסמכי תיעוד פוטנציאליים סגנונות ופורמטים ברורים, לקצר ולפשט את המדריכים הקיימים, להעביר הסברים לקטע נפרד ותורמי מסמכים חדשים יוכלו לתרום תרחישים לדוגמה לשימוש בקטע ההסברים בלי ליצור תיעוד מלא של Sphinx. אנחנו רוצים להמשיך ולבנות את קהילת ההוראה והלמידה.
שותפים ביצירת תיעוד חדשים יכולים לתרום תרחישים לדוגמה למיליוני משתמשים בלי לבנות את התיעוד המלא של הספינקס. אנחנו רוצים להמשיך ולבנות את קהילת ההוראה והלמידה. התיעוד המוצע יחקה את התיעוד הקיים של הקוד הפתוח כגון Matplotlib, Divio וכו'. למשתמשים חדשים ולתורמים פוטנציאליים יהיה קל יותר ללמוד ליישם את NumPy בשדות ובתוכנה שלהם.
לוח הזמנים לפרויקט הוא 14/9-30/11. השלב הראשון הוא ליצור את התיעוד ואת התוכן הנפרד של המדריכים הנוכחיים וליצור מהם חומרי הדרכה, הדרכות והסברים. הדבר יתבצע בחמשת השבועות הראשונים של הפרויקט כחלק מ'תוצאות 1' ו-'2' תיקון האתר והמדריכים, בהתאמה. הארגון המוצע לתיעוד מוצג במסמך המוצע בהמשך.
מסמכים מוצעים:
i.Tutorials:
- יסודות מוחלטים למתחילים (הסרת ההתקנה, האם ניתן להחליף את הייבוא/הייצוא של פנדות ב-numpy.loadtxt?)
- קישור למאמר "מה זה numpy"
- קישור להוראות התקנה בסיסיות כאן
- מדריך למתחילים (מיועד להמשך למדריך של Python)
- עבודה עם מערכים NumPy
- יצירת מערך (np.zeros , np.ones , np.block וכו') (כתיבה: עדיפות בינונית-נמוכה)
- פעולות ברמת הרכיב (+,-,*,/) ופעולות אלגברה ליניארית (+,-,@, linalg.solve) (עדיפות Write:med)
- קריאה וכתיבה של נתונים באמצעות Numpy (כתיבה: עדיפות גבוהה)
- הוספה לאינדקס
ii. הדרכות:
- אלגברה לינארית במערכים n-ממדיים (אשמח לערוך את הכותרות והתיאורים, ואולי לשנות את הכותרת ל'עיבוד תמונה עם אלגברה לינארית של Numpy')
- קישור לתוכן של מספר הדרכות לביצוע (עבודה מתמשכת)
iii. הסבר:
- סוגי נתונים
- קלט/פלט (I/O) עם Numpy
- הוספה לאינדקס
- שידור
- החלפת בייטים
- מערכים מובנים
- כתיבת קונטיינרים של מערך מותאם אישית
- מערך משנה של מחלקות
- שונות
iv. שטח הפניה:
- מילון מונחים
- הפניית API Numpy
- מספרי למשתמשי Matlab (טבלת שקילות היא טבלת הפניות נהדרת, אבל הדיון על מערכים/מטריצה מסיח את הדעת ונראה שהוצא משימוש)
לאחר השלמת העונה הזו של Google Docs, אני מציע את התוצאות הבאות:
- דף אינטרנט מתוקן של מסמכי תיעוד שמפריד באופן ברור בין ארבעת האזורים: מדריכים, הדרכות, הסבר והפניה
- מדריכים חדשים עבור: יצירת מערכים (np.zeros , np.ones , np.block וכו'), פעולות ברמת הרכיב (+,-,*,/) ופעולות אלגברה לינארית (+,-,@, linalg.solve) וקריאה וכתיבה של נתונים באמצעות Numpy (עדיפות גבוהה)
- מסמכי הדרכה מפורטים במטרה להגדיל את כמות התרומות למשתמשים ולעזור לקידום יעדי הקהילה בהוראה ובלמידה
לכל תוצאה יש מספר שלבים המפורטים בהמשך בטבלאות של תוצאות 1-3. בזמן שהמסמך המוצע נשלח לבדיקה, המדריך בעל העדיפות הגבוהה "מערכים לקריאה/כתיבה" ייכתב להגשה כבקשת משיכה כחלק מתוצאה 2. במהלך הבדיקה של האתר המתוקן והמדריך המעודכן "מערכים לקריאה/כתיבה", אתחיל לכתוב מדריך ליצירת מערכים באמצעות פונקציות NumPy, כגון np.ones , np.zeros , np.diag. הזמן שנותר ישמש לתגובה לבעיות בבקשות משיכה ולכתיבת המדריך לדירוג 3: פעולות אלגברה ברמת הרכיב ופעולות אלגברה לינארית ב-Python.
התוצאה השלישית היא לייעץ לסטודנטים באוניברסיטת קונטיקט לבנות מסמכים במאגר numpy-tutorials. המדריכים או מסמכי ההדרכה שיישלחו יהיו מסמכי notebook של Jupyter המשתמשים ב-NumPy כדי לפתור בעיות הנדסיות. אני אשתמש בחלק מההערות/הדוגמאות שלי כדי להגיש notebook לדוגמה. אני אמליץ לתלמידים לעקוב אחרי הפריסה והמבנה בזמן שאנחנו בונים תבנית וסכמת מסגור. התוצאה הזו מספקת לתלמידים ולתלמידות חוויה אמיתית שמאפשרת להם להעביר מושגים ופתרונות לקהל רחב יותר. זוהי הזדמנות נהדרת לתלמידים להיות מעורבים בקהילת NumPy וללמוד.
תוצאה 1: שינוי תאריך המסירה של האתר מאגר Fork ו-Build Docs עם Sphinx 21/9 בניית דף אינטרנט עם ארבעה מרחבים מוגדרים ומקושרים 10/1 העברת מדריכים עדכניים למקומות מתאימים ובניית מסמכים 10/10 שליחת יחסי ציבור ל-github עם הצעות לשינויים 11/1 2 2 להערות/הצעות ולתוצאה 1
תוצאה 2: שינוי הדרכות הגשה
דירוג מוצע של תיקונים במדריך (בכפוף לשינויים בהתאם למנטורים/קהילה):
קריאה/כתיבה של מערכים ריקים כרגע
יצירת מערך (np.zeros , np.ones , np.block וכו') לא קיים: יעזור למשתמשים חדשים להסביר ולהדגים את השימוש בכלי היצירה/האינטראקציה של מערכים משותפים
פעולות אלגברה לינאריות ומבחינת רכיב (+,-,*,/ ו- +,-@,linalg.solve) לא קיימות: אפשרות זו שימושית במיוחד עבור 1. משתמשי Matlab ו-2. אנשים שמשתמשים באלגברה לינארית (למידה חישובית, רגרסיה ליניארית וכו')
תוצאה 3: אוסף הנחיות לאיסוף תאריך הגשה של קישור חיצוני(בעיה/דוגמה)
בניית דוגמה 'כיצד לבצע' (מועמד: איך למצוא את התדרים הטבעיים של מחרוזות גיטרה 10/20
בניית תבנית 'כיצד לבצע' לתורמים חדשים 10/1 בתהליך התקדמות של תבנית מדריך PR ו'מסגור' ו'הצעות לרעיונות' ו'מסגור' עבור תלמידים ותלמידות אחרים שיוכלו ליצור סטטוס 'הדרכה' כדי ליצור מדריכים עם משתמשים חדשים10/1
המשמעות הצפויה
הצעה זו של Google Summer of Docs תיצור את התיעוד NumPy, תמלא את מערכי השיעור החסרים מהאתר ותצבור תורמי תוכן. כפרופסור בהנדסת מכונות, אני מתכנן לפלח את התיעוד כך שהתלמידים יוכלו לנווט במסמכים ולמצוא בקלות מדריכי מבוא לעומת מדריכים מעשיים. התיעוד המפולח: מדריך, הדרכה, הפניה והסבר יספקו לתורמים פוטנציאליים דוגמאות מובנות לפיתוח משאבים חדשים. התיעוד המוצע מאפשר מפגש של 'תן וקח' באמצעות חוויה של למידה ותקשורת למשתמשים חדשים ומנוסים. מסמך ההדרכה המוצע לייעוץ עם סטודנטים מאוניברסיטת קונטיקט יעמיד את הרעיון המחנך והתקשורת הזה ליישם אותו. אנחנו רוצים שכל המשתמשים ימצאו מקום להתנסות, ללמוד ולהצטרף לקהילת NumPy.
קובצי עזר
- האתר של NumPy.org ניגש בתאריך 07/2020.
- במאגר NumPy GitHub.
- מערכת התיעוד. גישה אל Divio.com בתאריך 07/2020.
- דיואי, ג'ון. דמוקרטיה וחינוך. פרויקט גוטנברג, אוגוסט 2015.
- דיואי, ג'ון. המסע ל-Certainty George Allen And Unwin Limited. 06/2005.