דף זה מכיל את הפרטים של פרויקט כתיבה טכני שהתקבל בעונת Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- NumPy
- כתב טכני:
- קופר
- שם הפרויקט:
- מסמכי תיעוד מספריים לחינוך קהילתי
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
מבוא
NumPy מספק מחשוב נקי ומהיר מבוסס מערכים בספריית תוכנה בקוד פתוח ללא תשלום. זוהי חבילה בסיסית בסטאק SciPy למחשוב מדעי [1]. יותר מ-370 אלף פרויקטים משתמשים במחשוב מערכים יעיל [2]. לפני המשתמשים של NumPy מופיע אתר חדש שכולל אפליקציות ומקרים לדוגמה [1]. כשמשתמש חדש מוצא את דף התיעוד, הוא נתקל בכמה קישורי 'התחל כאן' ומדריכי מבוא שעשויים להיות מסובכים למתחילים, כמו NumPy Basics/byte-swapping. התחלתי להשתמש ב-NumPy לפני עשר שנים בבית הספר המקצועי. מצאתי את עצמי לחבר פוסטים בבלוגים, הערות להרצאה ותשובות ל-StackExchange כדי לא לעבור על התיעוד של NumPy. כרגע יש יותר מ-360 אלף שיחות ב-StackExchange שקשורות ל-NumPy. אני חושב שלמשתמשים אחרים היו מסלולים דומים להצלחה ב-NumPy. אבני הבניין של כלים חינוכיים הן תקשורת וקהילה [4]. על המסמכים ליצור קהילה שמשקפת את היעדים הרצויים של הפרויקט. התיעוד צריך להיות מדריך ברור למשתמש חדש. המדריכים צריכים לספק למשתמשים חדשים שלבים קלים לביצוע, ולבנות תחושת נוחות בעזרת הספרייה [3]. התיעוד אמור לברך משתמש חדש שיצטרף לקהילת NumPy. המבנה, הקצב והמחברים של המסמכים צריכים ליצור מקום שמעודד חקירה ותקשורת. הצעה זו תארגן ותמלא פערים בתיעוד ה-NumPy הנוכחי, כדי שמשתמשים חדשים יכירו את הקהילה ויתקבלו בברכה.
הידע שהמשתמשים מתקשרים איתם נרכש על ידי בדיקה והתנסות [4,5]. הידע תלוי בשיטת הבדיקה וההערכה. תוכן שמספק מטרות עסקיות ואפליקציות ברורות בהדרכות מאפשר למשתמשים לבדוק ולהעריך רעיונות ושיטות חדשים. הקהילה יכולה לבנות מאגר ידע כדי לשפר מיומנויות, עובדות ואפליקציות. למרחב ההדרכה יש יתרון כפול. ראשית, למשתמשים חדשים ומנוסים יש יעדים ברורים שאפשר לבדוק וליצור מהם ניסויים. שנית, למשתמשים פוטנציאליים שמוסיפים תיעוד יש מרחב שבו הם יכולים לתאר את המטרות, השיטות והפתרונות שלהם. סביבת ההדרכה ממלאת צורך מיידי בהפיכת התיעוד של NumPy לנגיש יותר עבור משתמשים חדשים ותורמים אפשריים. ידע נוכחי
ג'ון דיואי אמר שהבסיס של הלמידה הוא חוויה אמיתית [4]. לקהילת NumPy יש כמות עצומה של ניסיון אמיתי שאפשר לשתף עם משתמשים אחרים. חינוך מושתת על קהילה ותקשורת. דף תיעוד מאורגן מאפשר למשתמשים חדשים ליהנות מ-NumPy. היא גם יוצרת תבנית מובנית לתורמים פוטנציאליים שיעזרו להם להעביר מידע על חוויות ב-NumPy.
יש ארבעה אזורים המקובצים באופן נרחב לתיעוד תוכנה [3]: מרחב הדרכה, מרחב תרגול, מרחב הסברים ומקום לעיון. התיעוד של NumPy כולל מספר מסמכים במרחב המדריך שמשלבים הסברים והסבר על מרחב התוכן במדריך. מרחב ההדרכה צריך להתמקד בחינוך המשתמש ולהשתמש בצעדים קלים חזרה להעברת רעיונות. מרחב ההדרכות מספק הליכים ממוקדי-יעדים יותר, שהמשתמשים יכולים ליישם באפליקציות בעולם האמיתי. במרחב ההסבר יש מידע מפורט על מחרוזות מסמכים (doc-string) בכל פונקציה. מערך השיעור הנוכחי ומרחבי ההדרכה הקיימים לא מוקפים באופן ברור, ולפעמים הם נכנסים למרחב ההסבר וההפניות. יש מדריך מצוין ל'מתחילים', ומשתמשי Matlab יכולים להיעזר בו כדי ליצור קוד NumPy בקטע NumPy למשתמשי Matlab. הפרדה ברורה בין ארבעת התחומים האלה תבהיר את התיעוד.
פער במאגר הידע/צורך שלא מולאו
המסמכים הנוכחיים כוללים הרבה נושאים הכרחיים, אבל אין הבחנה ברורה בין אזורי הדרכה, הוראות, הסברים ומרחבי הפניה. הפעולה הזו גורמת לבלבול אצל תורמים פוטנציאליים. משתמשים חדשים עלולים להפתיע משתמשים עם הסברים וחומרי עזר בסעיף ההדרכה, ומשתתפים פוטנציאליים מתמודדים עם מכשולים שיש להם הזדמנות לתרום. אני מציע פריסה נגישה יותר למשתמשים חדשים ולתורמים אפשריים לתיעוד, עם זרימה הגיונית בתיעוד וניהול בקשות משיכה למסמכי הדרכה שמשתמשים חדשים תרמו. המטרה שלי לטווח הארוך היא לבנות את קהילת התיעוד כך שהלמידה מהתיעוד תהיה חוויית למידה של 'נתינה והעברה'. מודל התיעוד הזה יבסס את החינוך על הניסיון של מצטרפים חדשים ותורמים פוטנציאליים.
פירוט הנימוקים
ההצעה הזו לקיץ של Google Docs חשובה ליעדים הפדגוגיים והקריירה שלי. אני משתמש ב-NumPy וב-SciPy בכל הקורסים שלי. לתלמידים שלי קשה לנווט בתיעוד הנוכחי. אני רוצה להשתמש בניסיון שלי בהוראה של תוכניות לימודים לקורסים שלא שייכים ל-CS, כדי לעזור לארגן, לערוך ולמלא את הפערים במדריכים הנוכחיים. לאחר מכן אוכל להשתמש במסמכים האלה כספר לימוד וחומר עזר לקורסים שלי. יצרתי עשרות מדריכים, תרגילים ודוגמאות באמצעות Python ו-
מטרות ספציפיות
יש לי שלוש מטרות ספציפיות להצעה הזו של Google Docs לקיץ של Google Docs: 1. מארגנים את המסמכים הנוכחיים, 2. עורכים את המדריכים הנוכחיים (המדריך למתחילים, יצירת מערך, הוספה לאינדקס, אלגברה לינארית ו-NumPy ל-Matlab) כדי להעביר מידע על ההפניות למרחב ההסבר, ו-3. לבנות חומרי הדרכה עם התלמידים. לכל מטרה ספציפית יש תוצאה צפויה מההצעה.
מטרת שלוש המטרות הספציפיות האלה היא ליצור תיעוד נעים יותר למשתמשים חדשים, ולספק מבנה לתורמים פוטנציאליים. המטרות גם עוזרות לקדם את המטרה ארוכת הטווח של הרחבת קהילת התיעוד של NumPy. תוצאות צפויות
יש לי שלוש תוצאות צפויות: 1. דף אינטרנט מתוקן שמפריד בבירור בין ארבעת התחומים: מדריכים, מדריכים, הסבר והפניות, 2. מדריכים חדשים לקריאה ולכתיבה של מערכים, יצירת מערכים (np.zeros, np.ones, np.block וכו') ופעולת אלגברה ברמת הרכיבים לעומת פעולה אלגברה לינארית במספרים, ו-3. מרחב הדרכה שנאסף.
התוצאות הצפויות האלה יעזרו למשתמשים חדשים להתקדם באמצעות מסמכים, יספקו שותפים פוטנציאליים לתיעוד עם סגנונות ופורמטים ברורים, יקלו על השימוש במדריכים הקיימים, יעבירו את ההסברים לקטע נפרד ותורמי מסמכים חדשים יוכלו להציע תרחישים לדוגמה קטנים לחלק של ההוראות מבלי ליצור את התיעוד המלא של Sphinx. אנחנו רוצים להמשיך לפתח את קהילת ההוראה והלמידה.
תורמי תיעוד חדשים יכולים לתרום מקרי שימוש קטנים למיליוני משתמשים בלי לפתח את כל התיעוד של Sphinx. אנחנו רוצים להמשיך לפתח את קהילת ההוראה והלמידה. מסמכי התיעוד המוצעים יחקו את התיעוד הנוכחי של הקוד הפתוח כגון Matplotlib, Divio וכו'. למשתמשים חדשים ולתורמים פוטנציאליים יהיה קל יותר ללמוד ליישם NumPy בשדות ובתוכנה שלהם.
לוח הזמנים לפרויקט הוא 14/9 עד 30/11. השלב הראשון הוא לפתח את התיעוד ואת התוכן הנפרד של המדריכים הנוכחיים וליצור מהם תכנים של מדריכים, הדרכות והסברים. השינוי יתבצע בחמשת השבועות הראשונים של הפרויקט כחלק מ'תוצאות 1' ו'תוצאות 1' ותיקון של האתר ומדריכים, בהתאמה. הארגון המוצע למסמכים מוצג בהמשך המאמר 'מסמכים מוצעים'.
מסמכים מוצעים:
i.Tutorials:
- יסודות מוחלטים למתחילים (הסרת התקנה, האם ניתן לייבא/ייצוא פנדה להחליף ב-numpy.loadtxt?)
- קישור אל "מה זה מספר טלפון"
- קישור להוראות התקנה בסיסיות כאן
- מדריך למתחילים (מיועד להמשך הדרכה בנושא Python)
- עבודה עם מערכי NumPy
- יצירת מערך (np.zeros , np.ones , np.block וכו') (כתיבה: עדיפות בינונית-נמוכה)
- פעולות ברמת הרכיבים (+,-,*,/) ופעולות אלגברה לינארית (+,-,@, linalg.solve) (עדיפות Write:med)
- קריאה וכתיבה של נתונים באמצעות Numpy (כתיבה: עדיפות גבוהה)
- הוספה לאינדקס
ii. מדריכים:
- אלגברה לינארית על מערכים חד-ממדיים (אשמח לערוך את הכותרות והתיאורים ואולי לשנות את הכותרת ל'עיבוד תמונה באמצעות האלגברה הלינארית של 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 9/21 בניית דף אינטרנט עם ארבעה רווחים מוגדרים ומקושרים ב-10/1 העברת מדריכים עדכניים למרחבים משותפים ובניית מסמכים 10/10 שליחת יח"צ ל-github עם שינויים מוצעים 11/1 מענה להערות/הצעות ולתיקון תקנה1 של האתר עם שינויים מתמשכים/10
תוצאה 2: תיקון מדריכים Deliverable Date סקירת מדריכים דירוג 9/21 הפרדת תוכן המדריך הנוכחי למרחבים של הדרכה והסבר 10/1 כתיבת דירוג 1: מערכים מסוג קריאה/כתיבה 10/10 שליחת PR ל-gitHub להפרדה ותיקון 10/20 כתיבת דירוג 2: Array1 Creation PR כתיבת דירוג 2: Array1 Creation PR
דירוג מוצע של תיקונים במדריך (כפוף לשינויים בהתאם למנטורים/קהילה):
דף ריק
יצירת מערך (np.zeros , np.ones , np.block וכו') לא קיים: יעזור למשתמשים חדשים לקבל הסברים על הכלים הנפוצים ליצירת מערכים/אינטראקציה עם המערך
פעולות אלגברה ליניאריות ו מבחינת הרכיבים (+,-,*,/ ו- +,-@,linalg.solve) לא קיים: זה שימושי במיוחד עבור 1. משתמשי Matlab ו-2. אנשים שמאמצים אלגברה לינארית (למידת מכונה, רגרסיה ליניארית וכו')
תוצאה 3: אוסף הדרכה בנושא תאריך אספקה קישור חיצוני(בעיה/דוגמה)
יצירת דוגמה להדרכה (מועמד: איך למצוא תדרים טבעיים במחרוזות גיטרה 20/10
יצירת תבנית הדרכה לתורמים חדשים 10/1 בתהליך הכנה של תבנית מערך שיעור יחסי ציבור וצירוף משתתפים אחרים למסגרות ככלי עזר כדי לגייס תלמידים וחברים אחרים לקבל סטטוס 'הדרכה' ולתרום לקהילות שלהם.
המשמעות הצפויה
הצעה זו של Google Summer of Docs תיצור את התיעוד NumPy, תמלא מדריכים חסרים מהאתר ותוסיף שותפים ביצירת התיעוד. כפרופסור בהנדסת מכונות אני מתכננת לפלח את המסמכים כך שהתלמידים שלי יוכלו לנווט במסמכים ולמצוא בקלות מדריכי מבוא לעומת מדריכים מעשיים. מסמכי התיעוד המפולחים: מדריך, הדרכה, הפניה והסבר יספקו לתורמים פוטנציאליים דוגמאות מובנות פוטנציאליות לבניית משאבים חדשים. התיעוד המוצע מאפשר להשתתף בחוויה של למידה ותקשורת בקרב משתמשים חדשים ומנוסים. מסמך ההדרכה המוצע לייעוץ עם סטודנטים מאוניברסיטת קונטיקט ייושם את הרעיון החינוכי והתקשורת הזה לתרגול. אנחנו רוצים שכל המשתמשים ימצאו מקום להתנסות, ללמוד ולהצטרף לקהילת NumPy.
קובצי עזר
- האתר של NumPy.org ניגש ל-07/2020.
- במאגר NumPy GitHub.
- מערכת התיעוד. גישה אל Divio.com ב-07/2020.
- דיואי, ג'ון. דמוקרטיה וחינוך. פרויקט גוטנברג, אוגוסט 2015.
- דיואי, ג'ון. Quest for Certainty George Allen And Unwin Limited. 06/2005.