הפרויקט של קרן Wikimedia

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

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

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

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

1. מידע כללי עליי

נחשפתי לשימוש בתוכנת קוד פתוח לפני מספר חודשים וכמעט מיד הרגשתי מבוהל מהיכולת האינסופית שלה. כשהתקשיתי לעשות את זה, למדתי על יוזמות של קוד פתוח כמו Google Summer of Code ו-reachy. העונה של Google Docs נראתה מעניינת והרעיונות לפרויקטים של קרן Wikimedia עוררו את סקרנותי, לכן התחלתי לחקור את הנושא.

עד עכשיו, מסע הפרסום שלי היה מלהיב ומבלבל, והכין כמה "רגע, מה?", "אהה, הבנתי!" ו"האם כדאי לי להגיב על זה?". קהילת Wikimedia תומכת בכל שלב ושלב. מעריכת דפים ועד ליצירת תוספים, אני למדתי משהו חדש כל יום.

כצפוי, תהליך הבקשה שימש כשער שלי לקהילת הקוד הפתוח. ההצעה הזו מבוססת על החוויות שלי כמתחילים.

2. פרויקט

2.1. קווי מתאר

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

2.2. פריטים נדרשים

  • T197006 [https://phabricator.wikimedia.org/T197006] - שיפור התיעוד לתיעוד של Wikimedia:

    • מוסיפים טיפים ודוגמאות למסמכי תיעוד/מדריך סגנון. [https://www.mediawiki.org/wiki/Documentation/Style_guide]
    • הוספת מידע ספציפי של MediaWiki לז'אנרים מסוימים בתבניות ובהצעות של מסמכים טכניים: מדריכים למשתמש, מדריכים, מדריכים למתחילים, נתוני גרסה וקובצי README. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • בדיקה ושיפור של ההנחיות לתעדוף מסמכים טכניים. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • תכנון אסטרטגיה לאיסוף תוכן עבור ז'אנרים שונים של תיעוד.
    • תכננו אסטרטגיה של תקשורת ושיתוף פעולה עבור התיעוד של MediaWiki.
    • כדאי ליצור רשימת משימות שלפיה הכותבים יוכלו לעיין במסמכים שלהם לפני הפרסום.
    • הרחבה של מבנה המסמכים לכותבים טכניים חדשים. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • איסוף רשימה של משימות של מסמכים טכניים שמתאימים להאקאתון. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • אפשר ליצור מרכז לכתיבה טכנית שמפנה למשאבים שימושיים.

  • שפר את התיעוד לצלמי הווידאו של MediaWiki:

    • יוצרים מדריך משתמש מהיר ליצירת הקלטת מסך כללית.
    • עיצוב תבניות של הקלטות מסך ספציפיות ל-MediaWiki, לקבלת הדרכות מפורטות ומדריכים.

  • T214522 [https://phabricator.wikimedia.org/T214522]– יצירת הקלטת מסך בשם "Introduction to Phabricator".

2.3. שער המשך

  • יש לבדוק שוב את התוכן ולעדכן את התיעוד של WikiProject Screencast. (https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)

3. מנטורים

Zulip תהיה אמצעי התקשורת העיקרי עם המנטורים שלי. ערוצי IRC והאימייל של Wikimedia ישמשו לדיונים עם הקהילה. דיונים על משימות ספציפיות יתבצעו בקטע התגובות של משימות ה-Pabricator.

4. קבוצת הדיון

הפרויקט מחולק באופן כללי לשני שלבים:

(i) שיפור המשאבים הקיימים לכותבים הטכניים של Wikimedia.

(ב) ליצור תבניות שימושיות לצלמי וידאו פוטנציאליים.

(i) שיפור המשאבים הקיימים לכותבים הטכניים של Wikimedia.

בעבר פעלו מספר יוזמות לשיפור התיעוד של MediaWiki, ברמות שונות של הצלחה. הנה כמה דוגמאות:

  • https://www.mediawiki.org/wiki/User:Zakgreant/Tech_DocsPlan(2011--01/P6M)
  • https://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan
  • https://www.mediawiki.org/wiki/Thread:Project:Current_issues/RestructureMediaWiki.org(or:_Document_how_it_was_and_execute_it)
  • https://www.mediawiki.org/wiki/User:Waldir/Docs

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

בהמשך מופיע קטע מתוך דוח דו-שבועי של מתמחה משנת 2018 בשם Anna e só https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/:

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

T197006 [https://phabricator.wikimedia.org/T197006] גם שופך אור על תחומים מסוימים של מסמכי כתיבה טכניים טעונים שיפור. ברור, תיעוד/מדריך הסגנון הוא המקום להתחיל.

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

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

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

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

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

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

(ב) ליצור תבניות שימושיות לצלמי וידאו פוטנציאליים.

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

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

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

בקטע שלמעלה מהמאמר "The Screencasting Handbook"" [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf], איאן אוזסוולד מסביר מה המשמעות של הקלטות מסך. הכלי יכול להיות שימושי במיוחד למדריכים בנושא הגדרת סביבת הפיתוח של MediaWiki, כתיבת תוספים, שימוש ב-Gerrit ועוד.

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

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

לבסוף, מקור ההפניה המרכזי לצלמי הווידאו של Wikimedia – WikiProject Screencast נבדק ומתעדכן.

5. ציר זמן לא סופי

תקופת גיבוש לקהילה (1 באוגוסט עד 1 בספטמבר)

  • אנתח את הפרויקט בפירוט עם המנטורים שלי.

  • דיון על:

    • באיזו תדירות צריך לבדוק את המשימות.
    • שיתוף לוחות זמנים והחלטה על תהליך עבודה שבועי/יומי.
    • הכלים והמשאבים שבהם אפשר להשתמש.
    • דוחות פרויקטים דו-שבועיים ויוממים.

  • יוצרים את המשימות ותתי-המשימות הנדרשות ב-Pabricator.

  • צרו טיוטות כדי לפצות על ההתחייבויות האישיות בשלב הפיתוח של המסמך.

שבוע 1 (2 עד 8 בספטמבר)

  • שיפור התיעוד/מדריך הסגנון:

    • לשנות את המיקוד העיקרי כדי להמחיש את השיטות המומלצות ואת הסטנדרטים ב-MediaWiki.
    • הוסיפו דוגמאות של עבודה טובה ושפר את החשיפה של דפים משויכים.

  • שיפור המדריך לכותבים טכניים חדשים:

    • מרחיבים את מבנה התיעוד.

שבוע 2 (9 עד 15 בספטמבר)

  • תעדוף של מסמכים טכניים:

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

שבוע 3 (16 עד 22 בספטמבר)

  • כדאי ליצור את המסמכים הנוספים הבאים לכותבים טכניים:

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

שבוע 4 (23 עד 29 בספטמבר)

  • הוסף מידע על כתיבה בז'אנרים הנפוצים ביותר של MediaWiki לתבניות ולהצעות של תיעוד טכני:

    • מתעדים ב-MediaWiki את השיטות המומלצות לכתיבת מדריכים למשתמש, מדריכים למתחילים, קובצי README, נתוני גרסה והדרכות.

  • הוסיפו הנחיות לשיפור יכולות התקשורת הטכנית. [https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation#Increasingmaturity--_strategic_directions]

שבוע 5 (30 בספטמבר עד 6 באוקטובר)

  • שיפור התיעוד עבור שותפי עריכה חדשים:

    • עדכון הדף: משימות של תיעוד טכני לאירועי האקאתון. (לביצוע: הוספת משימות מתאימות לדף זה במהלך תקופת הפרויקט)

  • יוצרים מרכזים לכותבים טכניים

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

שבוע 6 (7 עד 13 באוקטובר)

  • צור את המסמכים הבאים בנושא יצירת סרטונים עבור MediaWiki:

    • מדריך מהיר למשתמש בנושא 'יצירה של הקלטת מסך כללית' שמצביע על הפרויקט של Screencast.
    • תבניות עבור: הדרכות מפורטות בנושא שימוש בתוכנה/כלי; הדרכות בנושא פיתוח כלים חדשים.

  • יצירת רשימה של רעיונות להקלטת מסך עבור MediaWiki.

שבוע 7 (14-20 באוקטובר)

  • עבוד על הסרטון "מבוא ל-Pabricator":

    • אפשר להשתמש בתבנית (שנוצרה בשבוע הקודם) כדי ליצור טיוטה של סקריפט.
    • מעריכים את היעילות של התבנית ומשפרים אותה במקרה הצורך.
    • מקבלים משוב ומסיימים את הטיוטה.

שבוע 8 (21-27 באוקטובר)

  • פרסמו את סרטון המבוא ל-Phbricator:

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

שבוע 9 (28 באוקטובר עד 3 בנובמבר)

  • פועלים לשיפור התיעוד של פרויקט Screencast:

    • בדקו את המבנה ודון בכל צורך בשינויים.
    • בודקים את התוכנות שצוינו.
    • בודקים ומעדכנים את רשימת התוכנות.

שבוע 10 (4 עד 10 בנובמבר)

  • אפשר להמשיך לשיפור התיעוד של פרויקט Screencast:

    • הערכה ושיפור של המדריך והסקריפטים.
    • בודקים את גלריית הקלטות המסך.

שבוע 11 (11 עד 17 בנובמבר)

  • משלימים את העבודה על תיעוד הפרויקט של Screencast:

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

שבוע 12 (18 עד 24 בנובמבר)

  • עובדים על משימות שעוד לא בוצעו.

  • כותבים את הדוח הסופי:

    • יש לעיין בדוחות הדו-שבועיים/יומיים ולאסוף את המידע הנדרש.
    • צריך לתכנן את מבנה הדוח ולכתוב טיוטה.
    • משפרים ומסיימים את הטיוטה בהתאם למשוב של המנטור.

שבוע 13 (25 עד 29 בנובמבר)

  • הגשה של הדוח הסופי והערכה של המנטור.

6. מעקב אחר התקדמות

עדכונים יומיים על ההתקדמות יועברו למנטורים שלי ב-Zulip. קהילת Wikimedia יכולה לעקוב אחר ההתקדמות שלי באמצעות Phabricator או דוחות הפרויקט הדו-שבועיים.

7. מחויבויות אחרות

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

הבחינה הפנימית הראשונה: 18 עד 24 באוגוסט

בחינה פנימית שנייה: 29 בספטמבר עד 6 באוקטובר

בחינת סוף סמסטר: 11 עד 30 בנובמבר

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

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