פרויקט DIPY

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

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

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

DIPY

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

אזורה טאריק

שם הפרויקט:

שינוי מבני ברמה גבוהה והתמקדות במשתמשי הקצה

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

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

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

אני מהנדס תוכנה ומומחה בכתיבה טכנית. יש לי יותר מ-4 שנות ניסיון בכתיבת מסמכי תיעוד של תוכנות, מדריכים למשתמש, מדריכים ומתואר פרויקט באיכות גבוהה. אני גרה באיסלמבאד, פקיסטן (אזור זמן: UTC + 5). כרגע אני עובדת כמתמחה ב-Outreachy, והתפקיד יימשך עד 18 באוגוסט. השתתפתי בתוכנית Google Season of Docs ככותבת טכנית בארגון OpenELIS Global. המסמכים המקוריים היו בצרפתית, מוגבלים ומסורתיים, ולכן יצרתי מסמכים מקיפים ומעודכנים באנגלית למשתמשי קצה. נבחרתי ב-Wasy בארגון Perl ו-Raku למשך סביבות מאי-אוגוסט 2020, כמפתח/ת קצה עורפי של שרת Open Food Facts. מעבר לפיתוח עורפי, אחת המשימות העיקריות בהתמחות הזו היא ליצור מסמכים למודולים ולפונקציות בפורמט POD. נכנסתי לעולם הקוד הפתוח בשנה שעברה כשתרמתי לכמה פרויקטים של קוד פתוח, ולאחר מכן השתתפתי ב-Google Season of Docs. השנה נבחרתי לתוכנית Outreachy שתומכת במגוון בקוד פתוח ובתוכנות חינמיות. יש לי שליטה טובה ב-Git כי הפרויקט שלי ב-Outreachy מתארח ב-GitHub, ואני תורמת באופן קבוע ל-Open Food Facts ול-Mozilla Fenix מאז מרץ. אני משתמש ב-Linux מזה יותר מ-3 שנים ומשתמש בפקודות טרמינל מאז.

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

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

אני מתכוון לבצע את הפעולות הבאות:

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

מדריך למשתמש:

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

מדריך למפתחים:

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

TEMPLATE

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

תרומה ל-DIPY

• הודעת פתיחה

TOC

קוד ההתנהגות

• התקנים שלנו
• דוגמאות להתנהגות שתורמת ליצירת סביבה חיובית
• דוגמאות להתנהגות בלתי מקובלת של משתתפים
• תחומי האחריות שלנו
• האחריות של מנהלי הפרויקטים
• היקף

היקף קוד ההתנהגות

מה צריך לדעת כדי לעזור?

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

הגדרת סביבת הפיתוח

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

• קוד המקור: github.com/$project/$project
• מעקב אחר בעיות: github.com/$project/$project/issues

איך להוסיף תוכן

איך מדווחים על באג

• לפני שליחת דוח על באג
• איך שולחים דוח באג (טוב)?

איך שולחים שינויים

• פרוטוקולים של בקשות משיכה
• תגובה מהצוות
• מהירות התגובה

איך מבקשים שיפור

• לפני שליחת הצעה לשיפור
• איך שולחים הצעה לשיפור (טובה)?

הקוד הראשון שתוסיפו

• בעיות למתחילים
• בעיות שדרושה להן עזרה #### בקשת משיכה
• תהליך היצירה של בקשת משיכה
• מוודאים שכל בדיקות הסטטוס עוברות.

מה קורה אם בדיקות הסטטוס נכשלות?

• מבחנים בכתיבה
• בדיקת הכיסוי

מדריכי סגנון

• הודעות לגבי השינויים ב-Git
• סגנון רגיל

תמיכה

אם נתקלת בבעיות, אפשר לפנות אלינו. אם דרושה לך עזרה, אפשר לשאול שאלות ברשימת התפוצה שלנו בכתובת [e-mail], בצ'אט IRC או ב[רשימת פלטפורמות התקשורת האחרות שבהן נעשה שימוש בפרויקט].

רישיון

בסעיף הזה נסביר על הרישיון של הפרויקט.

התחייבות לזמן ולתקשורת:

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