פרויקט בוקה

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

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

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

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

יצירה, קריאה ושיתוף: אופטימיזציה של המסמכים של Bokeh

1. מופשט

Bokeh הוא כלי עוצמתי במיוחד ליצירת תצוגות חזותיות אינטראקטיביות מבוססות-דפדפן באמצעות Python. יש לה בסיס משתמשים גדול (502,000 הורדות חודשיות של conda, 855,000 הורדות של PyPi) ומספר גדול של שותפים (455 שותפים ב-GitHub). זה לא מפתיע שהתיעוד הנרחב של בוקה גדל באופן אורגני. לכן, בחלק מהמקרים, המידע לא עקבי, קשה לגשת אליו והוא מסובך.

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

כתבתי קוד ותיעדתי פרויקטים בקוד פתוח באמצעות Python ו-Sphinx (הפרויקטים האחרונים: PyZillow ו-PyPresseportal). אבל מה שמייחד אותי בתור משתתפת ב'עונת המסמכים' של Google הוא הרקע שלי בתחום העיתונות: עבדתי בחדרי חדשות במשך יותר מ-13 שנים, וגם שנים רבות כעורכת ראשית ותומכת בשינוי דיגיטלי. בנוסף לתפקידים העיתונאים שלי, היה לי תפקיד גדול יותר לעצב ולתעד כלים דיגיטליים חדשים ומדריכי סגנון חדשים, ולהכשיר אנשי צוות בחדרי החדשות.

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

2. המצב הנוכחי

המסמכים הרשמיים של Bokeh מורכבים מהיחידות העיקריות הבאות:

  • מסמכי תיעוד בפורמט סיפורי: מדריך התקנה, מדריך למשתמש, מדריך למפתחים, הערות מוצר
  • גלריה והדגמות (דוגמאות אינטראקטיביות עם קוד המקור שלהן)
  • מדריך עזר (מסמכי עזר שמבוססים על docstrings)
  • מדריך (אוסף נרחב של קובצי notebook של Jupyter שמתארחים ב-mybinder.org)
  • מסמכי עזרה ומודלים ל-IDE
  • דוגמאות ומסמכי README במאגר הפרויקט

בנוסף, יש שפע מידע בפורום התמיכה של Bokeh וב-Stack Overflow, שבו המפתחים של Bokeh עונים באופן פעיל על שאלות של משתמשים, וגם בבלוג של Bokeh ב-Medium.

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

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

לדוגמה:

דף הנחיתה של התיעוד של Bokeh קצר למדי ואינו כולל מידע על כל המשאבים הזמינים (אין אזכור של הספרייה הנרחבת של docstrings ופונקציות העזרה של המודלים, פורומי התמיכה, ההדגמות או הבלוג Medium). הדבר גם מקשה על משתמשים חדשים להתחיל לעבוד עם Bokeh.

3. יעדים

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

3.1. שפר את יצירת המסמכים

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

אעשה זאת בשתי דרכים:

  • אצור קבוצה של הנחיות סגנון מעשיות ופשוטה שכלולות במדריך הקיים למפתחים. ההנחיות האלה יעזרו לכם לשפר את הסגנון, הדקדוק והמבנה של הטקסט. בנוסף, אשתמש בערוצי תקשורת פנימיים כמו Slack כדי לוודא שהשותפים ליצירת Bokeh מודעים להנחיות הסגנון. בנוסף, אציע אימון אישי וסשנים של שאלות ותשובות לצוות.
  • אעבוד עם צוות הליבה כדי למצוא קבוצה אופטימלית של כלים לבקרת איכות של מסמכי העזרה, שתתווסף לתהליכי העבודה הקיימים של Bokeh לבקשות משיכה (PR) ול-CI (אינטגרציה רציפה). בהתאם לדרישות של הצוות, יכול להיות שתצטרכו להוסיף כלים כמו pydocstyle,‏ proselint או sphinxcontrib-spelling לבדיקת האיות של חבילת הבדיקות של Bokeh, להגדרה של 'שמירה לפני השמירה' או לפעולות ב-GitHub. הוספתי הוכחת קונספט עובדת לפעולות GitHub של אחד מהפרויקטים שלי בקוד פתוח.

3.2. לשפר את קריאת המסמכים

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

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

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

בדומה לשיפורים ביצירת מסמכים שצוינו למעלה, אתמקד ביצירת תשתית לשיפורים עתידיים ובשמירה על רמה גבוהה של תיעוד ב-Bokeh.

‫3.3. שיפור שיתוף המסמכים

יותר ויותר דיונים בנושא Bokeh מתנהלים בפלטפורמות של צד שלישי. בפלטפורמות רבות מהן נעשה שימוש במטא-נתונים, כמו OpenGraph של Facebook, כדי לכלול תצוגות מקדימות עשירות של קישורים. Open Graph משמש בשירותים כמו Facebook, Twitter, LinkedIn, Slack ו-iMessage. גם בפורום Discourse של Bokeh נעשה שימוש ב-OpenGraph כדי להציג תצוגות מקדימות של קישורים.

כדי להשתמש בטכנולוגיה הזו, אוסיף מטא-נתונים לדפי האינטרנט שנוצרו על ידי בוקה 'ספינקס', כפי שמתואר בבעיה #9792. הדרך היעילה ביותר היא להשתמש בתוסף ייעודי של Sphinx. לפני כמה ימים פרסמנו ב-GitHub את הגרסה הראשונה של תוסף Sphinx לנתוני OpenGraph. אני אשתמש בחלק משלב הפיתוח של מסמכים כדי לעזור בשיפור התוסף הזה לשימוש יחד עם המסמכים של בוקה.

יצרתי גם הוכחת תפיסה שאני משתמש בה בהצלחה באחד מהפרויקטים שלי בקוד פתוח, PyPresseportal. התוסף הזה אוסף באופן אוטומטי מידע רלוונטי כמו שם, תיאור, תמונה וכתובת URL. לאחר מכן, המידע הזה מוכנס לקוד ה-HTML שנוצר על ידי Sphinx בתור תגי OpenGraph.

השלב הבא בפיתוח התוסף הזה יהיה להציג הוראות בהתאמה אישית כדי להגדיר באופן ידני מטא-נתונים של OpenGraph (בדומה להוראות הקיימות של docutil מסוג 'meta'). המערכת תשתמש במטא-נתונים שנוצרו באופן אוטומטי רק כחלופה במקרה שאין נתונים זמינים שהוזנו באופן ידני.

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

החברים בקהילות Sphinx וב-ReadTheDocs הביעו עניין בפיתוח תוספים ל-Open Graph ונתונים מובנים (בנושאים #1758 ו-#5208, לדוגמה), ואני אקפיד לעבוד איתם בשיתוף פעולה הדוק.

4. תוצרים

לסיכום, אלה התוצרים שאני מצפה להם בסיום Season of Docs:

  • הנחיות לסגנון המסמך עבור תורמי תוכן ב-Bokh
  • שינוי תהליכי העבודה של בקשות תיקון (PR) ו-CI כך שיכללו בקרת איכות אוטומטית של מסמכי תיעוד
  • מדריך למשתמש נערך ומאורגן מחדש
  • דף הנחיתה המעודכן של התיעוד
  • מטא-נתונים של OpenGraph שכלולים בדפי האינטרנט של המסמכים ותוסף Sphinx שפועל

בנוסף, אכתוב 'יומן מסמכים' כדי לתעד את המסע שלי במסגרת 'עונת המסמכים' של Google באתר האישי שלי ב-Medium או בבלוג של Bokeh ב-Medium. הדיווח הזה ישמש גם כבסיס לדוח הפרויקט ל-Google. אעשה את כל העבודה באופן שקוף, ככל האפשר, באמצעות בקשות תמיכה ובקשות משיכה ב-GitHub.

5. ציר הזמן

לפני שלב ההתחברות לקהילה: כבר השתתפתי באופן פעיל בכמה דיונים במאגר GitHub של Bokeh, וקיימתי קשר עם Bryan Van de Ven ו-Pavithra Eswaramoorthy, המנטורים של Bokeh ב-Season of Docs של Google. אמשיך להיות פעיל בשיחה על Bokeh, ואשתמש ב-Bokeh כדי ליצור ולפרסם הדמיות חזותיות, וכך להכיר את הכלי טוב יותר.

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

  • הכרת הצוות הליבה, שיפור תוכנית הפרויקט בשיחות עם המנטורים
  • הגדרת לוח זמנים וערוצי תקשורת לדיווח ולקבלת משוב באופן קבוע מהמנחים
  • היו פעילים ב-Slack של Bokeh כדי להודיע לכל תורמי התוכן ב-Bokה שמתעניינים בעונת הקניות של Google Docs ובנוגע ליעדים של שלב פיתוח המסמך
  • לקבל משוב ממשתמשים של Bokeh כדי לשפר את התוכנית של שלב פיתוח המסמך

שלב פיתוח המסמך

שבוע 1, 14 בספטמבר עד 20 בספטמבר:

  • תחילת הביקורת והעריכה של תיעוד הנתונים
  • תחילת העבודה על טיוטה של הנחיות סגנון

שבוע 2, 21 בספטמבר עד 27 בספטמבר:

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

שבוע 3, 28.09 עד 04.09:

  • השלמת ההנחיות בנושא סגנון
  • סיום העבודה על דף הנחיתה של התיעוד

שבוע 4, 5 באוקטובר עד 11 באוקטובר:

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

שבוע 5, 12 באוקטובר עד 18 באוקטובר:

  • פגישה של שאלות ותשובות עם שותפי התוכן של Bokeh ב-Slack, כדי לדון בהנחיות סגנון, בשיפורים במסמכי העזרה ובתהליכי העבודה של PR/CI
  • אתחיל לפתח את הוכחת ההיגיון שלי למטא-נתונים של Open Graph לתוסף Sphinx שניתן לפריסה
  • משנים את הנחיות הסגנון על סמך המשוב מסשן השאלות והתשובות עם תורמי התוכן של Bokeh

שבוע 6, 19 באוקטובר עד 25 באוקטובר:

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

שבוע 7, 26.10-21.11:

  • בדיקה של תוסף Sphinx
  • סשן שאלות ותשובות שני עם שותפי הפיתוח של Bokeh ב-Slack
  • שינויים במוצרים הדיגיטליים על סמך המשוב מהסשן השני של שאלות ותשובות

שבוע 8, 2 בנובמבר עד 8 בנובמבר:

  • פריסה של תוסף Sphinx ופרסום של מסמכי עזרה משופרים ודף נחיתה של מסמכי העזרה

שבוע 9, 11/09 עד 15/11:

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

שבוע 10, 16 עד 22 בנובמבר:

  • השלמת המשימות שנותרו

שבוע 11, 23/11 עד 29/11:

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

שלב השלמת הפרויקט

שבוע 12, 30 בנובמבר עד 5 בדצמבר:

  • סיום ושליחה של דוח הפרויקט

שבוע 13, 3/12 עד 12/10:

  • השלמה ושליחה של הערכת הפרויקט

בסיום 'עונת המסמכים' של Google:

  • אני מקווה להמשיך להיות מעורב בפיתוח של Bokeh ולהמשיך לעבוד על התיעוד של Bokeh.
  • אני מתכנן להמשיך בפיתוח של תוסף Sphinx למטא-נתונים של OpenGraph או של נתונים מובְנים.
  • אני מקווה להשתמש ברקע שלי בתחום העיתונות ובקשרים הקיימים שלי כדי לקדם את Bokeh ככלי בתחום עיתונות הנתונים. לדוגמה, אפשר לכתוב על Bokeh תוך התמקדות בקהל עיתונאי, או להציע הרצאות בכנסים על השימוש ב-Bokeh בסביבות עיתונאיות.

6. מידע עליי

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

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

ספרי העזר והמסמכים שכתבתי בעבודה הקודמת אינם ציבוריים, לצערי. לכן, עכשיו אני מתמקדת במעורבות רבה יותר בפרויקטים של קוד פתוח (דוגמאות מפורטות בהמשך). העבודה שלי בכתיבה טכנית מבוססת על מדריכי סגנון כמו מדריך הסגנון של Google לכתיבת מסמכים למפתחים ומדריך הסגנון של Microsoft. אני משתמש/ת באופן קבוע ב-GitHub, ב-Slack וב-Linux. כתבתי מסמכי עזרה ותיאוריים, וגם docstrings והצעות לסוגים, באמצעות כלים כמו Sphinx, ‏ Mypy ו-Sphinx autodoc.

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

7. דוגמאות למסמכים אחרונים בקוד פתוח

  • PyZillow: PyZillow הוא מעטפת Python ל-API של אתר הנדל"ן Zillow.com. בנוסף ליצירת קוד מסוים ולפעולה כאחד מהמפתחים של הקוד, כתבתי את המסמכי התיעוד המלאים. השתמשתי ב-Sphinx לתיעוד הקריינות וגם להפניה למודול. יצרתי את ההפניה למודול באמצעות המסמך האוטומטי של תוסף Sphinx, על סמך קובצי ה-docstring שהוספתי לקוד.

  • PyPresseportal: ‏PyPresseportal הוא מעטפת Python ל-API של האתר presseportal.de. האתר presseportal.de הוא אחד המפיצים הגדולים של הודעות לעיתונות והודעות בנושא קשרי משקיעים בגרמניה. לדוגמה, כמעט כל תחנות המשטרה והכבאות משתמשות בשירות הזה כדי להפיץ את הודעות העיתונות שלהן. אחרי שנים של שימוש ב-API כעיתונאי, החלטתי לפתח ממשק Python כדי לגשת למשאבי הנתונים הנרחבים של האתר כאובייקטים של Python. כתבתי את הקוד ואת כל המסמכים המבוססים על ספינקס.