דף זה מכיל את הפרטים של פרויקט כתיבה טכני שהתקבל בעונת Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- Cloud Native Computing Foundation (CNCF)
- כתב טכני:
- שריטי
- שם הפרויקט:
- שיפור התיעוד של SMI ורשתות שירות קשורות
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
המטרה של טכנולוגיית Service Mesh היא, בעצם, לתת ערך לכמות השירותים ההולכת וגדלה, על ידי טיפול בכל צורכי האבטחה, הניהול והניטור שלכם. Service Mesh Interface (SMI) מגדיר קבוצה של ממשקי API למקרי השימוש הנפוצים ביותר ב-Service mesh (מדיניות תעבורת נתונים, טלמטריה והעברות) ומאפשר תאימות בין Service meshes, שהן שכבות תשתית ייעודיות לטיפול בתקשורת בין שירותים בסביבת מיקרו-שירותים. תקינה של הממשקים האלה תספק חוויה משופרת של משתמש קצה, ולכן היא יעד עתידי עבור SMI ורשתות שירות קשורות.
המצב הנוכחי:
מדריכים למשתמש: SMI הוא פרויקט ארגז חול חדש יחסית, שנתרם ל-CNCF באפריל 2020. כתוצאה מכך, אין לפרויקט תיעוד של משתמשי הקצה. Meshery הוא מישור ניהול שירותים עם השוואה של ביצועים לכל סוגי השירותים שמאפשרים אימוץ, הגדרה, תפעול וניהול הביצועים של רשתות שירות שונות. הוא כולל איסוף והצגה של מדדים מאפליקציות שפועלות על גבי כל רשת Service mesh. הייתי רוצה להתחיל עם מדריך ל-Meshery, שישמש כנקודת התחלה לכל קהילת משתמשי SMI.
מדריכים למשתמש: בין פלטפורמות ה-SMI הקיימות: היישום לדוגמה, Learn Layer5, משמש כיום ככלי למידה ל-SMI וכיישום לדוגמה לביצוע אימות של מפרט SMI.לעומת זאת, בפרויקטים של SMI אין בכלל מדריכים למשתמשי קצה, מה שיוצר מכשול חמור בגלל האופי הטכני מאוד של הפרויקטים. Meshery הוא האפליקציה המושלמת להצגת היתרונות של SMI ורשתות השירות הקשורות אליו, ושימוש בו, ולכן אשתמש בו ככלי הבסיס להצגת התכונות של SMI.
תיעוד API: לא קיים כרגע. ל-SMI ולפרויקטים קשורים שונים יש נקודות קצה ל-API מוגדרות בפלטפורמה. לדוגמה, נקודות הקצה של Meshery מוגדרות ב-server.go (https://github.com/layer5io/meshery/blob/master/router/server.go), אבל הן לא קיבלו תגובה טובה ולא תועדה אף אירוע חיצוני. ניתן לפתור זאת באמצעות תיעוד משמעותי של ה-API, וניתן לשפר אותו על ידי הוספת דרכים למשתמשים לבדוק את נקודות הקצה שלו ולראות תצוגה מקדימה של התכונות שלו.
ניתוח:
מדריכים למשתמש נוצרים כדי לאפשר למשתמשים להתנסות בתוכנה ולהתנסות בה. הן צריכות להיות אינטראקטיביות ומושכות מבחינה אסתטית כדי למשוך את תשומת הלב של המשתמש, והכי חשוב, קלים לשימוש.
עם זאת, אם כותבים או מארחים מדריכים למשתמש, מומלץ להשתמש בפורמט למבוגרים בלבד כי המדריכים למשתמש הם לרוב מדריך למשתמש או מקום שבו אפשר למצוא פתרון מהיר לבעיות. במקום להיות אינטראקטיביים, המודעות צריכות להיות בנויות בצורה טובה ולהתמקד בשיפור הבהירות, העקביות וזרימה האיכותית של המשתמשים.
פתרון אפשרי הוא ליצור מדריכי משתמש נפרדים באמצעות Google Codelabs ומדריך משתמש עצמאי בעזרת Jekyll ולבסוף שילוב שלהם יחד עם מסמכי התיעוד של ה-API, כדי לספק חוויה מקיפה הן למשתמש הקצה והן לשותפי עריכה בעתיד.
קהל היעד: פרויקטים של SMI מספקים שיטות פריסה ותפעול, סביבות למידה ונקודות השוואה של ביצועים לכל הפרויקטים שבהם הם פועלים. הוא משרת אנשים פרטיים וגם ארגונים.
מדריכים למשתמש: אתמקד במשתמשים מתחילים, ללא הנחות לגבי ידע קיים ב-IT מבחינת המשתמשים. יעד: משתמשים מתחילים הסיבה: משמש בעיקר כמדריך עיון נרחב, שיעבור עדכון של הזמן הנדרש. התוכנית תכלול הסברים מפורטים וטיפים שימושיים שיבטיחו שלמשתמש יש את כל המידע שצריך כדי להגדיר רשת Service mesh ולעבוד איתה. כדי להפוך את המדריך למעניין ולידידותי יותר למשתמש, כדאי להוסיף סרטונים, תמונות, צילומי מסך וקובצי GIF, אם יהיה צורך.
מדריכים למשתמש: יעד: משתמשים מתחילים הסיבה: המטרה היא שהמדריכים יהיו מעניינים ואסתטיים, כדי לשמור על תשומת הלב של המשתמשים ולהפעיל בדיקה חלקה של התוכנה. כך תוכלו להבין טוב יותר את ממשק Service Mesh.
תיעוד של נקודות קצה ל-API: יעד: משתמשים מתקדמים הסיבה: הקטע הזה מתמקד בשימוש בתכונות המורכבות יותר של Service mesh, שחשוב יותר למשתמשים מתקדמים בעלי ידע בסיסי ב-IT. משתמשים מתקדמים יחפשו מדריכים תמציתיים שיכולים לשמש גם כמדריכים למקרה הצורך. התיעוד של נקודות הקצה צריך להיות מנוסח כך שיהיה קל לעדכן אותו בלי לפגוע בדיוק או בעקביות שלו. עדיף לעשות זאת בתהליך אוטומטי.
משאבים: מדריכים למשתמש: Google Developers Codelab – משמש ליצירת מדריכים אינטראקטיביים ומקיפים למשתמשי הקצה. יתרונות: - יכולת ליצור מדריכים לארגז חול. - יש גישה מעשית. - נכתב באמצעות Google Docs ותומך בטקסט Markdown. - ניתן לעקוב אחרי תנועת המשתמשים באמצעות Google Analytics. קל לזהות את תנועת המשתמשים. - קל לשימוש. יצירה של מדריכים אסתטיים שמאפשרים למשתמש להתנסות בתוכנה באופן ישיר, ללא השקעה ישירה.
אפשר לשפר ולפרוס בקלות את Google Codelabs באמצעות פרויקט CLaaT (Codelabs כ-Thing). זוהי תוכנית שמציעה כלי שורת פקודה שמשמש להמרת מדריכים שנכתבו ב-Google Docs באמצעות Markdown לפורמט codelabs (HTML).
מדריכים למשתמש: Jekyll - התיעוד הקיים של meshery.io, הזמין כאן, מתארח ב-Jekyll ומבוסס על העיצוב Docsy Jekyll. המערכת משתמשת ב-Markdown, נוזל, HTML ו-CSS כדי ליצור אתרים סטטיים ומוכנים לאירוח, ופועלת בסביבת פיתוח של Ruby. יתרונות: - אפשר לארח אתרים ישירות ממאגרי GitHub. - פרויקט נתמך היטב עם קהילה פעילה מאוד - ניתן פשוט להוסיף מדריכים למשתמשים ושיפורים למסמכי התיעוד הקיימים של SMI ו-Meshery, ללא הטרחה של מעבר לפלטפורמה אחרת.
תיעוד API: סוואג (לחלופין, Swaggo) ישמש ליצירת מסמכי ה-API עבור SMI ו-Meshery. זהו פתרון אלגנטי לכתיבת מסמכי API. יתרונות: - תיעוד מעיצוב ה-API: מבטיח שהמסמכים יהיו מעודכנים ככל שה-API מתפתח. - תיעוד מעיצוב ה-API: אפשר ליצור באופן אוטומטי מהגדרות ה-API. - ניהול מספר גרסאות של תיעוד - עיצובי API מותאמים אישית
יעדי הפרויקט: - להשתמש ב-Google Developers Codelabs כדי ליצור מדריכים אינטראקטיביים למשתמשי קצה עבור SMI ו-Service meshes קשורים באמצעות Meshery ככלי. - יצירת מדריך למשתמש קצה באמצעות Jekyll עבור Service meshes. - שימוש ב-Sagger כדי ליצור תיעוד של נקודות קצה ל-API עבור SMI. - מעודדים את קהילת הפרויקט לפעול כדי שמשתמשים או מפתחים עתידיים ונוכחיים יוכלו בקלות להמשיך להוסיף לפרויקט תחת הדרכה וניהול של קהילת SMI.
ציר הזמן: ניתן למצוא את ציר הזמן המוצע כאן: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl
מבנה: ניתן למצוא את המבנה המוצע למדריך למשתמש כאן: https://docs.google.com/document/d/1A3YYAMUTe06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
למה דווקא הפרויקט הזה? קהילת Service mesh מתרחבת בקצב מסחרר, והיא מתאפשרת בזכות השילוב האחרון שלה כפרויקט ארגז חול ב-CNCF. עם זאת, אנחנו עדים למחסור משמעותי במסמכים, גם למשתמשי הקצה וגם למפתחים. שיחקתי בעבר עם מגוון Service meshes, כולל linkerD עם אפליקציית EmojiVoto, Istio עם אפליקציית פרטי הספר והקונסול של Hashicorp. ניסיתי גם להשתמש בחלוקת תנועה של SMI ויישמתי כללי אימות שונים בהגדרות של Service mesh. תהליך הלמידה מרתק אבל גם טכני מאוד, והוא עשוי להקשות על משתמשים חדשים ועל מפתחים שרוצים לעשות את צעדיהם הראשונים בקהילת Service mesh או להשתמש ב-Service mesh בפרויקטים אישיים או מקצועיים. אני רוצה לגשר על הפער הזה, שאפשר לעשות אותו רק באמצעות מדריכים ומדריכים יעילים ומתועדים היטב.