פרויקט DIPY

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

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

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

DIPY

כתב טכני:

ארישה טאריק

שם הפרויקט:

ארגון מחדש ברמה גבוהה והתמקדות במשתמשי הקצה

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

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

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

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

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

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

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

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

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

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

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

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

TEMPLATE

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

תרומה ל-DIPY

• מכתב ברכה

TOC

קוד ההתנהגות

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

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

מה חשוב לדעת כדי לעזור?

אם אתם רוצים לקבל עזרה בתרומת קוד בפרויקט שלנו, אנחנו משתמשים ב[insert list of program language, frameworks, or Tools that project available]. אם אתם עדיין לא מוכנים לתרום קוד, אין בעיה! אפשר גם לעיין בבעיות במסמכים [link to the docs label or tag on your issue tracker] או בעיות עיצוב שיש לנו [link to Design label or tag on issue tracker [אם הפרויקט שלכם עוקב אחר בעיות בעיצוב]. אם אתם רוצים לתרום קוד ולקבל מידע נוסף על הטכנולוגיות שבהן אנחנו משתמשים, עיינו ברשימה שבהמשך. כדאי לכלול רשימת תבליטים של משאבים (מדריכים, סרטונים, ספרים) שהשותפים החדשים יכולים להשתמש בהם כדי ללמוד מה המשתמשים צריכים לדעת כדי לתרום לפרויקט.

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

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

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

איך מוסיפים תוכן

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

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

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

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

איך לבקש שיפור

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

תרומת הקוד הראשונה שלך

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

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

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

מדריכי סגנון

• הודעות Git שמירה
• סגנון רגיל

תמיכה

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

רישיון

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

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

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