בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- Django
- כותבים טכניים:
- Gabbyprecious
- שם הפרויקט:
- המדריך לשכתוב התרומות כדי שיהיה ידידותי יותר למשתמש וקל לנווט בו
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
ABSTRACT
המטרה של מדריך התרומות של Django, כמו כל מסמך אחר, היא להדריך משתמשים, ובמקרה הזה תורמים בקוד פתוח, איך ואיפה הם יכולים לתרום לשיפור ולקיימות של Django.
תמיד יש צורך ביצירת מסמכי עזרה, במיוחד כאלה שיש להם השפעה רבה על הקהילה ועל Django עצמו.
המטרה של Django ב-Google Summer of Docs השנה היא להפוך את מדריך התרומות ליותר נגיש, ידידותי ומזמין לתורמים. זהו יעד חיוני כי הוא מעודד שותפים, ואני עצמי נמנה עליהם, להתחיל לתרום למסגרת הנהדרת הזו.
מצב נוכחי
השלב הנוכחי של המסמכים שזמינים כאן הוא לא ממש מדריך, כי הוא עמוס מדי ולא מובנה היטב, והוא מוביל להבנה פחותה של התרומה ל-Django ולא מזמין תורמים חדשים.
יעדי הפרויקט
דנתי בהצעות לתיעוד עם המדריך שלי, קרלטון גיבסון, בפורום והוא מאשר שזה יעזור עם הבעיה העצומה של המסמכים הנוכחיים. אלה היעדים שאני מתכנן להשיג באמצעות שינוי המבנה של המסמך: שינוי המבנה של המסמך הוספת קטעים עם 'מה מותר לעשות' ו'מה אסור לעשות' יצירת דפים בודדים לקטעים טריוויאליים כמו 'בקשה לתכונות חדשות ויצירת תכונות חדשות' מסמכי עזרה מקוצרים וברורים יותר מילון מונחים אינדקס פנימי שנבנה בהתאם למדריך החדש כתיבת מסמכי עזרה ידידותיים יותר ותואמים יותר לקוראים פילוח התוכן לשני חלקים עיקריים (קטע למתחילים וקטעים למשתתפים מתקדמים) יצירת מדריך וסגנון לכותבים טכניים חדשים/למשתתפים חדשים, כדי שהמסמכים יהיו מעודכנים ויעמדו בסטנדרטים.
התיעוד הנוכחי מיועד כבר לתורמים מתקדמים, ולא נותן הזדמנות לתורמים חדשים ומתחילים, גם בקוד פתוח וגם ב-Django. ריכזנו כאן כמה תכנים נוספים למתחילים: קטע שמנחה קבוצות שונות של תורמים(כותבים טכניים, מעצבים ומפתחים) דף שמתעד בעיות של משתמשים בפעם הראשונה ובעיות פשוטות שאפשר לפתור. אפשר לבחור כמה קטעים מהמסמכי העזרה הקיימים, לכתוב אותם מחדש ולהוסיף אותם לקטע למתחילים. קטעים שמסבירים נקודות או מילים עיקריות שמופיעות בקטע המתקדם.
ציר הזמן
כאן אביא פירוט של האופן שבו אני רוצה לעבוד על יעד הפרויקט כפי שצוין למעלה, באמצעות היומן ש-Google מספקת.
כלים
Sphinx – הכלי הנוכחי למסמכי העזרה הנוכחיים. קוראים את המסמכים.
למה דווקא הפרויקט הזה?
אני מאמין מאוד במסמכי עזרה ומאמרים שנכתבים בצורה טובה, כדי שכל אחד בעולם יוכל להבין אותם. בנוסף, אני אוהב את Django ואת קוד המקור הפתוח באופן כללי. אני רוצה לתרום ל-Django בתור מתחיל, ואני חושב שזו דרך מושלמת לתרום לכלי המועדף עליי, תוך היכרות עם קוד הבסיס כדי שאוכל לתרום יותר בתור מפתח(וגם ככותב טכני). אשמח לעבוד עם ארגון שתואם לדעות שלי ושימש אותי ככלי מצוין לכל אורך הקריירה שלי.
למה אני האדם המתאים לפרויקט הזה?
לדעתי, אני האדם המתאים לכך על סמך החשבונות הבאים: כתבתי מאמרים בנושא Django כדי לעזור למתחילים להבין טוב יותר את הקונספט של Django. אני מפתחת ומשתוקקת לתרום ל-Django, ולכן אני מבינה את הצורך של מפתחים אחרים ואת האופן שבו צריך לתעד אותו בצורה טובה בשבילם. אני שחקן/ית בצוות, ואעבוד טוב פחות או יותר תחת פיקוח של החונך שלי קרלטון גיבסון.