דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- קרן Cloud Native Computing Foundation (CNCF)
- כתב טכני:
- שריטי
- שם הפרויקט:
- שיפור התיעוד של SMI ורשתות שירות קשורות
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
המטרה העיקרית של טכנולוגיית Service Mesh היא לספק ערך מוסף למספר השירותים ההולך וגדל, באמצעות טיפול בכל צורכי האבטחה, הניהול והמעקב שלכם. Service Mesh Interface (SMI) מגדיר קבוצה של ממשקי API לתרחישי השימוש הנפוצים ביותר ב-Service mesh (מדיניות תעבורת נתונים, טלמטריה ושינויים) ומאפשר תאימות בין מחרוזות שירות (service mesh), שהן שכבות תשתית ייעודיות לטיפול בתקשורת שירות-לשירות בסביבת מיקרו-שירותים. הסטנדרטיזציה של הממשקים האלה תשפר את החוויה של משתמש הקצה, ולכן היא מהווה יעד עתידי עבור SMI ורשתות שירות קשורות.
מצב נוכחי:
מדריכים למשתמשים: SMI הוא פרויקט חדש יחסית לארגז חול שנתרם ל-CNCF באפריל 2020. כתוצאה מכך, אין בפרויקט תיעוד של משתמשי הקצה. Meshery הוא מישור לניהול שירותים עם השוואה של ביצועים לכל סוגי השירותים, שמאפשרים את ההטמעה, ההגדרה, ההפעלה והניהול של הביצועים של רשתות שירות שונות. השירות כולל איסוף והצגה של מדדים מאפליקציות שפועלות על גבי כל רשת שירות (service mesh). לכן הייתי רוצה להתחיל עם מדריך ל-Meshery, שישמש כנקודת התחלה לכל קהילת משתמשי ה-SMI.
הדרכות למשתמש: בין פלטפורמות ה-SMI הקיימות: האפליקציה לדוגמה, Learn Layer5, משמשת כרגע ככלי למידה ל-SMI וכאפליקציה לדוגמה לביצוע תיקוף של מפרט SMI.לעומת זאת, בפרויקטים של SMI אין בכלל מדריכים למשתמשי קצה, מה שמקשה מאוד בגלל האופי הטכני של הפרויקטים. Meshery הוא האפליקציה המושלמת להצגת היתרונות של SMI ו-Service meshes הקשורים אליו, והשימוש בו מוצלח. לכן אני אשתמש בו ככלי הבסיסי להצגת התכונות של 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. משתמשים מתקדמים יחפשו מדריכים תמציתיים שיכולים לשמש גם כמדריכים במקרה הצורך. התיעוד של נקודות הקצה (endpoint) צריך להיות כתוב כך שיהיה קל לעדכן אותו בלי לפגוע בדיוק או בעקביות שלו. עדיף לעשות זאת בתהליך אוטומטי.
משאבים: מדריכים למשתמש: 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: הסוואג (לחלופין, סוואגגו) ישמש ליצירת מסמכי התיעוד של ה-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. עם זאת, קיים מחסור חמור בתיעוד הפרויקט, גם למשתמשי הקצה וגם למפתחים. שיחקתי בעבר עם כמה רשתות שירות שונות, כולל linkerD עם אפליקציית אמוג'יVoto, Istio עם אפליקציית Bookinfo והקונסול של Hashicorp. ניסיתי גם את חלוקת התנועה של SMI והטמעתי כללי אימות שונים בהגדרה של Service mesh. תהליך הלמידה מרתק אבל מאוד טכני, והוא עשוי להקשות על משתמשים חדשים ועל מפתחים שרוצים לעשות את הצעדים הראשונים שלהם בקהילת ה-Service mesh או להשתמש ברשת Service mesh בפרויקטים אישיים או מקצועיים משלהם. אני רוצה לגשר על הפער הזה. אפשר לעשות זאת רק באמצעות מדריכים ומדריכים יעילים ומתועדים היטב.