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

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

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

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

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

1. פרטים עליי

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

המסע שלי עד כה היה מרגש ומבלבל באותה מידה, מלא ברגעים של "רגע, מה?", "אה, הבנתי!" ו"האם כדאי לי להגיב על זה?". קהילת 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] – יצירת הקלטת מסך של Phabricator.

2.3. יעד נוסף

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

3. מנחים

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

4. דיונים

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

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

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

(1) שיפור המשאבים הקיימים לכותבים הטכניים של 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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  • אפשר לדון בנושאים הבאים:

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

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

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

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

  • שפר את מסמכי התיעוד/Style_guide:

    • להתמקד בעיקר בהמחשת השיטות המומלצות והתקנים ב-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 באוקטובר)

  • עבודה על הסרטון 'מבוא ל-Phabricator':

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

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

  • מפרסמים את הסרטון 'מבוא ל-Phabricator':

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

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

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

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

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

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

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

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

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

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

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

  • עבודה על משימות בהמתנה.

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

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

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

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

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

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

7. התחייבויות נוספות

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

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

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

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

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

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