פרויקט Rocket.Chat

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

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

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

Rocket.Chat

כתב טכני:

מיסטר גולד

שם הפרויקט:

הבוטים Docs

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

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

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

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

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

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

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

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

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

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

הצעת פרויקט

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

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 repos) שצריך להעביר לתיעוד הראשי. - להגדיר איך אתרים של בוטים יפעלו לאחר ההעברה. - מגדירים תבנית שתשמש לארגון המידע במאגרים האלה. - מכינים את המסמכים העיקריים להעברה

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

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

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

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

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

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

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

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

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

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

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

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

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

גיבוש קהילה

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

שבוע 1 - שבוע 2

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

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

המסמכים המעודכנים יתמקדו בנושאים הבאים: - מפתחים חדשים שרוצים ליצור בוט משלהם - מפתחים מקצועיים של [בוט] שרוצים לעצב, לקודד או לבדוק את הבוטים שלהם באמצעות פלטפורמה חינמית וקלה לשימוש, או להסתגל לבוטים הקיימים שלהם לפלטפורמה הזו - מפתחי בוטים מקצועיים עם העדפות framework שרוצים ליצור בוטים ל-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/#twitter-to-your-bot)

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

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

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

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

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

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

שבוע 3 עד 9

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

1. הגדרה

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

2. תבנית

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

   a. שכפול מאגר

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

   ג. הגדרת בוט

   ד. הפעלת בוט

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

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

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

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

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

3. הכנה

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

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

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

4. העברה

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

   • הרצת בוטים
     • בוט בוט
     • בוט Hubot
     • בוט בוטים
     • ראסה בוט
     • בוטים לבוטים

5. ארגון

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

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

- למה המדיניות הזו חשובה? - בכל 8 פרויקטים המשנה שנתמכים על ידי Rocket.Chat: alexa, Hubot, chatops-gitsy, botpress, rasa, bbot, botkit, BOTswaa, 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. הגדרת המקום שבו יפורסמו פריטי מידע שנוצרו בתהליך הפיתוח (Artifact) של מסמכי JSDoc
4. תיאור של כל הפונקציות (ב-dist/lib/driver.js) שקשורות לשיטות של מנהל ההתקן. האמצעים האלה כוללים:
   • הוספה/עריכה של תיאורים של שיטות
   • הוספה/עריכה של תיאורים של פרמטרים של שיטות
   • הוספה/עריכה של דוגמאות של בקשות לשיטה, אם רלוונטי
   • הוספה/עריכה של דוגמאות של תשובות שיטה, אם רלוונטי

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

שבוע 11

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

שבוע 12

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