פרויקט Rocket.Chat

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

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

ארגון קוד פתוח:

Rocket.Chat

כותבים טכניים:

זהב גדול

שם הפרויקט:

מסמכי העזרה של ה-Bot

אורך הפרויקט:

אורך רגיל (3 חודשים)

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

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

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

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

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

בעיות בפרויקט

ריכזנו כאן רשימה של הבעיות החשובות ביותר שקשורות למסמכי התיעוד של ה-bots:

1. מידע כללי לא אינטואיטיבי ולא ידידותי על בוטים
2. קטעים מפוזרים ועודפים שקשורים לארכיטקטורה של בוטים
3. קטעים לא מאורגנים של הוראות במדריך 'תחילת העבודה', ללא מקור מידע יחיד
4. חוסר הוראות או רמת פירוט מוגזמת של ההוראות
5. תיעוד סמלי ומעורפל של Bot SDK

הצעת פרויקט

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

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

   • סקירה כללית על בוטים: https://rocket.chat/docs/bots/
   • ארכיטקטורה של בוטים: https://rocket.chat/docs/bots/bots-architecture/
   • הגדרת סביבות של בוטים: https://rocket.chat/docs/bots/configure-bot-environment/
   • דף הבית של הבוטים: https://github.com/RocketChat/rocketchat.github.io/pull/

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

3. מצגת Revise Rocket.Chat JS SDK של SDK. יש ליצור את מסמכי התיעוד של ה-SDK באופן פרוגרמטי מקוד המקור באמצעות כלים מיוחדים. השיפור הזה ישפר את הקריאוּת ויבטל את הצורך לעדכן את המסמך ב-Github באופן ידני בכל פעם ששיטה (או משהו בתוכה) משתנה.

מהלך המשחק

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

יצירת קשרים בקהילה: היכרות עם הקהילה. בדיקת המצב הנוכחי של מסמכי התיעוד של הרובוט. זיהוי נקודות חולשה.

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

שבוע 2: סקירה כללית של הבוטים, ארכיטקטורה, הגדרת הדפים של הסביבה

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

שבוע 4: העברת מאגר bBot ארגון המידע בהתאם לתבנית שהוגדרה

שבוע 5: העברת המאגר של Hubot. ארגון המידע בהתאם לתבנית שהוגדרה

שבוע 6: העברת המאגר של Botkit. ארגון המידע בהתאם לתבנית שהוגדרה

שבוע 7: העברת המאגר של Rasa. ארגון המידע בהתאם לתבנית שהוגדרה

שבוע 8: העברת המאגר של BotPress. ארגון המידע בהתאם לתבנית שהוגדרה

שבוע 9: סיום של מבנה המסמכים הראשי והדפים אחרי העברת כל פרויקטי המשנה של ה-Bot

שבוע 10: בדיקת ההגדרות של JSDoc. מגדירים מקום לאחסון ארטיפקטים של JSDoc. תחילת תיעוד השיטות של ה-driver

שבוע 11: השלמת תיעוד השיטות של מנהלי ההתקנים

שבוע 12: הערכת התוצאות

פירוט של יעדים

תקופת בדיקת הבקשה

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

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

קישור בין חברי הקהילה

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

שבוע 1 – שבוע 2

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

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

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

היקף העבודה יהיה:

1. להסיר קטעים מיותרים. לדוגמה, בקטעים הבאים יש מידע חופף:
   • איך בוטים שולחים ומקבלים הודעות? סקירה כללית של הבוטים (https://rocket.chat/docs/bots/#how-do-bots-send-and-receive-messages)
   • זרמי הודעות בארכיטקטורה של בוטים (https://rocket.chat/docs/bots/bots-architecture/#message-streams)
   • איך מדברים עם הבוט במאמר 'יצירת משתמשים בבוט' (https://rocket.chat/docs/bots/creating-bot-users/#talk-to-your-bot)

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

   לשנות סעיפים וביטויים לגבי המידע "מאחורי הקלעים":

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

3. צריך לכתוב מדריך למתחילים שבו מתוארים השלבים הדרושים ליצירת בוט (עם קישור אל "הגדרת סביבות בוט" כהמשך קריאה). המדריך הזה יופיע בדף Configuration of Environment.

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

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

שבוע 3 עד 9

השבועות 3 עד 9 יוקדשו לאיחוד כל מסמכי הרובוטים במאגרי GitHub ולהעברת המסמכים האלה למסמכי העזרה הראשיים (https://rocket.chat/docs/bots/). אפשר לחלק את הפעילויות האלה לכמה מחזורים:

1. הגדרה

   הגדרת רשימה של פרויקטים משניים של הרובוט שצריך להעביר למסמכי העזרה הראשיים. להגדיר איך אתרי הבוטים יפעלו אחרי ההעברה (לחלק מהבוטים, למשל bbot‏ (http://bbot.chat), יש אתרים נפרדים עם מסמכי עזרה בנוסף ל-GitHub).

2. תבנית

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

   א. שכפול מאגר

   ב. התקנת יחסי תלות

   ג. הגדרת בוט

   ד. הפעלת בוט

   ה. תצורה מתקדמת

   ו. שלבים נוספים

   הפקודות שכוללות פלט לא טריוויאלי (כמו ""run a bot"") צריכות להיות מלוות בהצגות של הפלט הזה בזמן אמת באמצעות הכלי Term Sheets (https://neatsoftware.github.io/term-sheets/).

   בנוסף, כדי להבהיר את השלב הראשוני של ""ההתחלה המהירה"" (שלבים א' עד ד'), כל השלבים ישולב גם במצגת אחת בשידור חי.

   כדי שמשתמשים חדשים ירגישו בטוחים מפני כשלים פוטנציאליים, כדאי לספק דוגמאות לקוד בסביבת ה-playground (באמצעות Glitch, כחלק מסביבת Rocket Chat), שבה משתמשים חדשים יכולים להתכתב בצ'אט עם בוטים שמשתמשים בקוד לדוגמה.

3. הכנה

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

   המבנה הסופי עשוי להיראות כך:

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

4. העברה

   העברת פרויקטי המשנה של הרובוט שהוגדרו למסמכי העזרה הראשיים, אחד אחרי השני. לכל חלק מהמסמכים של ה-bot יהיה דף נפרד עם קטעים משנה, כמו הגרסה הנוכחית (למשל, הפעלת bBot).

   • הפעלת בוטים
     • רובוט ענק
     • בוט Hubot
     • בוט Botkit
     • ראסה בוט
     • בוט בוט

5. ארגון

   יהיו כמה פעילויות:

   1. ארגון המידע מכל מאגר GitHub של הבוט בהתאם לתבנית שהוגדרה בשלב השני.
   2. העברת רכיבים נפוצים (למשל משתני סביבה) שקשורים לכל פרויקטי המשנה של הרובוטים רמה אחת למעלה בהיררכיה של המסמכים הראשיים, וקישור של פרויקטי המשנה של הרובוטים לרכיבים האלה
   3. יצירת דוגמה של בוט "hello World" לכל מסגרת נתמכת. הדוגמה הזו תשמש בתור בוט 'תחילת העבודה' ב-Rocket.Chat.

- למה המדיניות הזו חשובה? - בכל 8 הפרויקטים המשניים הנתמכים על ידי Rocket.Chat: alexa, ‏ hubot, ‏ chatops-gitsy, ‏ botpress, ‏ rasa, ‏ bbot, ‏ botkit, ‏ BOTswana, ‏ hubot-gitsy יש מסמכים מפוזרים בצורת קובצי README למפתחים. למסמכי ה-README האלה אין מבנה בכלל, הם מכילים מידע לא עדכני על תחילת העבודה או מכילים יותר מדי מידע (לפעמים עם יתירות משולשת, כמו במסמך של hubot (https://github.com/RocketChat/hubot-rocketchat) על הפעלת בוט באמצעות Docker), וגם את הטבלה שמכילה משתני סביבה.

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

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

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

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

שבוע 10

השבוע נתמקד בהגדרת JSDoc‏ (https://devdocs.io/jsdoc/) כדי למקסם את הערך של תגובות בקוד. בין היתר, אסור:

1. מוודאים ש-JSDoc מוגדר כראוי לניתוח תגובות לשיטות נהיגה (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods)
2. מתקינים את postman-jsdoc-theme‏ (https://github.com/postmanlabs/postman-jsdoc-theme) כדי שהפלט של ה-HTML שייווצר יהיה ברור יותר ונוח יותר למפתחים.
3. הגדרת המקום שבו יפורסמו ארטיפקטים של מסמכי תיעוד של JSDoc
4. תיאור כל הפונקציות (בקובץ dist/lib/driver.js) שקשורות לשיטות של הנהג. החוויה הדיגיטלית הזו צריכה לכלול:
   • הוספה או עריכה של תיאורים של שיטות
   • הוספה או עריכה של תיאורים של פרמטרים של שיטות
   • הוספה או עריכה של דוגמאות לבקשות של שיטות, אם רלוונטי
   • הוספה או עריכה של דוגמאות לתגובות של שיטות, אם רלוונטי

מבחינת המפתחים, קל יותר לכתוב ולתחזק מסמכי תיעוד בקוד מאשר מסמכים סטטיים. מנגנון היצירה האוטומטית של מסמכי התיעוד מאפשר להיפטר ממסמכי תיעוד סטטיים שמתארחים ב-GitHub (https://github.com/RocketChat/Rocket.Chat.js.SDK#driver-methods) שצריך לעדכן בנפרד בכל שינוי בשיטות ה-SDK.

שבוע 11

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

שבוע 12

סיום העבודה שהושלמו. בדיקות אישור.