השלב הנוכחי:
תוכנית 'עונה של 2019' של Docs הסתיימה ב-6 במרץ 2020. אפשר לראות
את ציר הזמן.
דף זה כולל הנחיות לכותבים טכניים בנוגע ליצירת דוח הפרויקט שלכם אחרי סיום העבודה לעונה של Docs עבור השנה.
שליחת דוח הפרויקט
כששלב הסיום של הפרויקט ייפתח, תוכלו להגיש את דוח הפרויקט באמצעות מילוי טופס שיהיה זמין בקטע של השלמת הפרויקט במדריך הטכני לכתיבה.
מידע שייכלל בדוח הפרויקט
בקטע הזה מתואר סוג המידע שאפשר לספק בדוח הפרויקט. טופס דוח הפרויקט יכלול שדות טקסט חופשי ושאלות אמריקאיות.
קישור לעבודה שלך
יש לספק קישור המפנה אל תיאור של העבודה שביצעת.
הקישור צריך להפנות למסמך שיש בו תיאור קצר של העבודה שהתבצעה, את התיעוד שהפרויקט בקוד פתוח מיזג עם המאגר שלו, סיכום של המצב הנוכחי של הפרויקט ורשימה של אתגרים ותובנות.
הקישור יופיע בתוצאות העונה של Docs שמפורסמות באתר. התוצאות שפורסמו ממחישות את העבודה שהשלמתם בתוכנית. התוצאות שפורסמו הן גם דרך מצוינת להתייחס לעבודה שלכם כחלק מקורות החיים.
כדאי לשתף את הקישור עם המנטור ולבקש בדיקה לפני הגשת דוח הפרויקט.
הדרישות לדוח הפרויקט
חשוב להביא בחשבון את הדרישות הבאות:
- התוכן המקושר חייב לאפשר זיהוי קל של העבודה שהשלמתם במהלך העונה של Docs, כלומר, השינויים שביצעתם או המסמכים החדשים שכתבתם.
- העבודה צריכה להיות במיקום יציב. לא ניתן לשנות את כתובת ה-URL לאחר השליחה.
צריך לאפשר למישהו אחר להשתמש בתוכן (או שיש אליו הפניה) מהיעד של הקישור, כדי להתבסס על היצירה שלכם.
- אם העבודה שלכם הושלמה ב-100%, לאנשים אחרים צריכה להיות אפשרות להשתמש בה.
- אם העבודה לא הושלמה ב-100%, צריך להיות ברור מה צריך לעשות.
דוגמאות טובות לתיאור העבודה שלך
אין חובה לבצע את כל הפעולות הבאות (או חלק מהן), אך יש כמה דרכים שבהן תוכלו לעמוד בדרישות:
צרו פוסט בבלוג או דף אינטרנט או מאמר ציבורי ב-GitHub, שמתאר את העבודה שעשיתם וקישורים אל ההתחייבויות שעשיתם ולמאגרים שעבדתם עליהם. אם יש עוד עבודות שצריך לעשות בפרויקט, הוסיפו תיאור שלו. תוכלו גם לשתף רגעים בולטים או דברים מאתגרים.
זו האפשרות הטובה ביותר כי היא מאפשרת לכלול בקלות מידע רב. כדאי לעשות זאת, כי בעזרתם תוכלו לראות בבירור את העבודה שעשיתם ואחרים יהיה קל להשתמש בכם ולהבין את התרומה שלכם.
אם אתם משתמשים ב-GitHub וכל העבודה שלכם נכללת בבקשת משיכה אחת, תוכלו להשתמש בקישור הזה.
- יש לוודא שהתיאור של בקשת המשיכה מפורט.
- ודא שהתיאור מציין באופן ברור שהיצירה מיועדת לעונה של Docs.
- אם בקשת המשיכה מצריכה עבודה נוספת אחרי סיום העונה של Docs, ודאו שהעונה האחרונה של Docs מציינת עובדה זו.
- היתרון בשיטה הזו לשליחת דוח על הפרויקט הוא: יומן השינויים, רשימת ההתחייבויות והתגובות על הבדיקה מרוכזים במקום אחד.
אם המאגר ב-GitHub מיועד רק לעונה של Docs, צריך להוסיף קובץ README שמכיל את פרטי העבודה.
יוצרים תיקייה ציבורית ב-Google Drive וכוללים את כל התיקונים שיצרתם.
יוצרים גיליון אלקטרוני ציבורי באמצעות Google Sheets ורושמים את כל ההתחייבויות.
קישור לגיליון יחיד למעקב ציבורי אחר בעיות, שמכיל הפניות ברורות לעבודה שלכם וכל תוכן רלוונטי אחר. הבעיה צריכה לעקוב אחרי כל הפעולות שעשיתם. ודאו שבבעיה מפורטות כל ההתחייבויות, או שקל למצוא את ההתחייבויות בדרך אחרת.
קישור להבדלים מאוחדים או להקשר של השינויים. חשוב לכלול כותרת שכוללת את השם של פרויקט הכתיבה הטכנית שלך ואת השם שלך, כדי שזה יועיל לאחרים.
דוגמאות לא תקינות שמתארות את העבודה
אין לבצע את הפעולות הבאות:
- תוכלו לקשר לקובץ tarball או לקובץ ZIP שמכילים את כל קוד המקור של הפרויקט או את ספריית העבודה.
- קישור לחלק העליון של מאגר המקור הראשי של הפרויקט לדוגמה, אם אתם עובדים על cpython, הקישור הזה לא שימושי: https://github.com/python/cpython.
- קישור לשכפול של מאגר המקור של הפרויקט. לכן קשה לראות מהם השינויים שלכם, מפני שהעבודה שלכם כוללת שילוב של עבודה של אנשים אחרים.
- קישור לתיאור הפרויקט באתר 'העונה של Docs'.
למנטורים
כדאי לעזור לכותב הטכני ליצור דוח פרויקט מתאים. חשוב לעשות זאת לפני שאתם יוצרים הערכה משלכם לעבודת הכותב הטכני.
מומלץ לבדוק ולבצע את הדברים הבאים:
- ההגשה צריכה לעמוד בדרישות המפורטות למעלה.
- הבקשה צריכה לכלול תיאור של העבודה שנעשתה, הדרישות שהוענקו והסיבות להחלטות ספציפיות שהתקבלו.
הרעיון של 'עונת המסמכים של Docs' הוא לא שכותבים טכניים נוטשים הרבה מסמכים. חשוב שהעבודה הזו תוכל להועיל לפרויקט האירוח של קוד פתוח.