פרויקט בוקה

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

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

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

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

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

1. מופשט

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

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

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

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

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

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

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

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

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

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

לדוגמה:

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

3. שערים

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

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

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

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

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

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

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

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

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

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

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

יותר ויותר דיונים סביב בוקה מתקיימים בפלטפורמות של צד שלישי. רבות מהפלטפורמות האלה משתמשות במטא-נתונים, כמו OpenGraph של Facebook כדי לכלול תצוגות מקדימות עשירות של קישורים. OpenChart משמש שירותים כמו Facebook, Twitter, LinkedIn, Slack ו-iMessage. גם בפורום Discourse של בוקה משתמשים ב-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 פעיל

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

5. ציר הזמן

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

שלב החיבור לקהילה (17/08 עד 13/09):

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

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

שבוע 1, 14/09 עד 20/09:

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

שבוע 2, 21/09 עד 27/09:

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

שבוע 3, 28/09 עד 4/10:

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

שבוע 4, 5/10 עד 11/10:

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

שבוע 5, 12/10 עד 18/10:

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

שבוע 6, 19/10 עד 25/10:

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

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

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

שבוע 8, 11/2 עד 11/08:

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

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

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

שבוע 10, 16.11 עד 22.11:

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

שבוע 11, 23 באוקטובר - 29 בנובמבר:

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

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

שבוע 12, 30 באוקטובר - 12/05:

  • הכנה ושליחה של דוח הפרויקט

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

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

בסיום העונה של Google Docs:

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

6. על עצמי

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

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

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

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

7. דוגמאות למסמכי תיעוד של קוד פתוח מהזמן האחרון

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

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