פרויקט Rocket.Chat

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

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

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

Rocket.Chat

כתב טכני:

מיסטר זהב

שם הפרויקט:

מסמכי הבוט

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

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

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

סיכום פרויקט

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

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

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

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

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

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

הצעה לפרויקטים

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

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

   • סקירה כללית של הבוטים: 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. שינוי מצגת התיעוד של Rocket.Chat JS SDK. יש ליצור את התיעוד של ה-SDK באופן פרוגרמטי מקוד המקור באמצעות כלים מיוחדים. השיפור הזה יהפוך את הקריאות ויבטל את הצורך לעדכן את המסמך ב-GitHub באופן ידני בכל פעם ששיטה (או משהו בתוכה) משתנה.

מהלך המשחק

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

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

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

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

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

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

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

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

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

שבוע 8: העברת מאגר Bot Press. ארגון המידע לפי התבנית המוגדרת

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

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

שבוע 11: סיום תיעוד שיטות הנהגים

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

פירוט יעדים מפורט

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

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

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

גיבוש קהילה

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

שבוע 1 - שבוע 2

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

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

המסמכים המעודכנים יתמקדו בנושאים הבאים: - מפתחים חדשים שרוצים ליצור בוט משלהם - מפתחים מקצועיים של [בוט] שרוצים לעצב, לקודד/לבדוק את הבוטים שלהם באמצעות פלטפורמה חינמית וקלה לשימוש, או להסתגל לבוטים הקיימים שלהם לפלטפורמה הזו - מפתחי בוטים מקצועיים עם העדפות המסגרת שלהם שרוצים ליצור בוטים ל-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. כותבים מדריך למתחילים שמתאר את השלבים הדרושים ליצירת בוט (עם קישור ל"הגדרת סביבות של בוטים" כקריאה נוספת). המדריך הזה יוצג בדף 'הגדרת סביבה'.

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

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

שבוע 3-9

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

1. הגדרה

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

2. תבנית

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

   a. שכפול מאגר

   b. יחסי תלות של התקנות

   ג. הגדרת בוט

   ד. הפעלת בוט

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

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

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

   יתרה מכך, כדי שהשלב הראשוני של 'התחלה מהירה' (שלבים א - ד) יהיה ברור יותר, כל השלבים ישולבו גם במצגת חיה אחת.

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

3. הכנה

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

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

   • בוטים
     • ארכיטקטורת בוטים
     • יצירת משתמשים בבוטים
     • הגדרה של סביבת הבוטים
     • הרצת בוטים
       • בוט בוט
       • הובוט בוט
       • בוט Kit
       • ראסה בוט
       • בוט לחץ

4. העברה

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

   • הרצת בוטים
     • בוט בוט
     • הובוט בוט
     • בוט Kit
     • ראסה בוט
     • בוט לחץ

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. כדי שפלט ה-HTML שמתקבל יהיה מפורש וידידותי יותר למפתחים, יש להתקין את postman-jsdoc-theme (https://github.com/postmanlabs/postman-jsdoc-theme)
3. הגדרת המקום שבו יפורסמו פריטי המידע של מסמכי JSDoc
4. תיאור כל הפונקציות (בקובץ Dist/lib/driver.js) שקשורות ל-methods של מנהל ההתקן. האמצעים האלה כוללים:
   • הוספה/עריכה של תיאורים של שיטות
   • הוספה/עריכה של תיאורים של פרמטרים של שיטות
   • הוספה/עריכה של דוגמאות של בקשות לשיטה, אם רלוונטי
   • הוספה/עריכה של דוגמאות לתשובות לשיטה, אם רלוונטי

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

שבוע 11

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

שבוע 12

השלמת העבודה שהושלמה. בדיקות קבלה.