פרויקט בוקה

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

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

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

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

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

1. מופשט

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

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

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

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

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

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

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

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

רוב דפי האינטרנט לתיעוד נוצרים באמצעות Sphinx, באמצעות מספר תוספי Sphinx סטנדרטיים ומותאמים אישית. מדריך העזר נוצר, למשל, ממחרוזות מסמכים (docstring) באמצעות תוספים כמו autodoc ו-'bockh_autodoc' בהתאמה אישית. כמו מטבעו של תיעוד בהגדלה אורגנית, הוא מכיל עודפים וחוסר עקביות.

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

לדוגמה:

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

3. שערים

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

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

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

אקפיד על כך בשתי גישות:

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

3.2. שיפור הקריאה במסמכים

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

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

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

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

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

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

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

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

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

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

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

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

לסיכום, אלה התכנים שאני מצפה שיגיעו בעונה של Docs:

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

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

5. ציר הזמן

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

שלב גיבוש הקהילה (08/17 - 09/13):

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

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

שבוע 1, 14.9 עד 20.9:

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

שבוע 2, 21.9 עד 27.9:

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

שבוע 3, 28.9 עד 04.10:

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

שבוע 4, 05.10 עד 11.10:

  • השלמת העריכה של התיעוד התיאורי
  • שוחח עם צוות הליבה של Bokeh לגבי שילוב כלים לבקרת איכות מסמכים בתהליכי עבודה של PR/CI

שבוע 5, 12.10 עד 18.10:

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

שבוע 6, 19.10 עד 25.10:

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

שבוע 7, 26/10 עד 11/11:

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

שבוע 8, 11/02 עד 8/11:

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

שבוע 9, 09.11 עד 15.11:

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

שבוע 10, 16.11 עד 22.11:

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

שבוע 11, 23.11 עד 29.11:

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

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

שבוע 12, 30.11 עד 5.12:

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

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

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

בסיום תקופת הניסיון של Google Docs:

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

6. מידע על עצמי

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

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

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

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

7. דוגמאות אחרונות לתיעוד של קוד פתוח

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

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