בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- Cloud Native Computing Foundation (CNCF)
- כותבים טכניים:
- Shriti
- שם הפרויקט:
- שיפור המסמכים של SMI ורשתות service mesh קשורות
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
המטרה העיקרית של טכנולוגיית Service Mesh היא לספק ערך מוסף לשירותים, תוך טיפול בכל צורכי האבטחה, הניהול והמעקב שלכם. ממשק Service Mesh (SMI) מגדיר קבוצה של ממשקי API לתרחישים הנפוצים ביותר של שימוש ב-Service Mesh (מדיניות תעבורה, טלמטריה והעברה), ומאפשר תאימות בין Service Meshes, שהם שכבות תשתית ייעודיות לטיפול בתקשורת בין שירותים בסביבת מיקרו-שירותים. הסטנדרטיזציה של הממשקים האלה תספק חוויית משתמש משופרת, ולכן היא יעד עתידי עבור SMI ורשתות שירות קשורות.
המצב הנוכחי:
מדריכים למשתמשים: SMI הוא פרויקט ארגז חול חדש יחסית, שנתרם ל-CNCF באפריל 2020. כתוצאה מכך, בפרויקט חסר מסמך תיעוד למשתמש הקצה. Meshery הוא מישור לניהול שירותים עם מדדי ביצועים לכל סוגי השירותים, שמקל על אימוץ, הגדרה, הפעלה וניהול של הביצועים של רשתות Service Mesh שונות. הוא משלב איסוף של מדדים מאפליקציות שפועלות מעל כל רשת Service Mesh, ומציג אותם. לכן, רציתי להתחיל עם מדריך ל-Meshery, שישמש כנקודת התחלה לכל קהילת המשתמשים של SMI.
מדריכים למשתמש: ביניהן, אפליקציית הדוגמה Learn Layer5 משמשת כרגע כמכשיר למידה ל-SMI וכאפליקציית הדוגמה שבה מבצעים אימות של מפרט SMI.אבל חוץ מזה, בפרויקטים של SMI אין בכלל מדריכים למשתמשי קצה, וזו בעיה רצינית בגלל אופי הפרויקטים הטכני מאוד. Meshery היא האפליקציה המושלמת להצגת היתרונות והשימוש ב-SMI ובשירותי הרשת המשויכים, ולכן אשתמש בה ככלי הבסיסי להצגת התכונות של SMI.
מסמכי תיעוד ל-API: לא קיימים כרגע. נקודות הקצה ל-API של SMI ושל פרויקטים קשורים שונים מוגדרות בפלטפורמה. לדוגמה, נקודות הקצה של 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 as a Thing) – זוהי תוכנית שמציעה כלי בשורת הפקודה שמשמש להמרת מדריכים שנכתבו ב-Google Docs באמצעות Markdown לפורמט של Codelabs (HTML).
מדריכים למשתמש: Jekyll – מסמכי התיעוד הקיימים של meshery.io, שאפשר למצוא כאן, מתארחים ב-Jekyll ומשתמשים בנושא Docsy Jekyll. הוא משתמש ב-Markdown, ב-liquid, ב-HTML וב-CSS כדי ליצור אתרים סטטיים מוכנים לאירוח, והוא פועל בסביבת פיתוח של Ruby. יתרונות: - אפשרות לארח אתרים ישירות ממאגרים של GitHub. - זהו פרויקט עם תמיכה רחבה וקהילה פעילה מאוד. - מדריכים למשתמש ושיפורים יכולים להתווסף בקלות למסמכי התיעוד הקיימים של SMI ו-Meshery, בלי צורך לעבור לפלטפורמה אחרת.
תיעוד API: Swagger (או Swaggo) ישמש ליצירת תיעוד ה-API של SMI ו-Meshery. זהו פתרון אלגנטי לכתיבה של מסמכי API. היתרונות: - תיעוד מהעיצוב של ה-API: מוודא שהמסמכים יישארו מעודכנים ככל שה-API יתפתח. - תיעוד מעיצוב ה-API: ניתן ליצור אותו באופן אוטומטי מהגדרות API. - ניהול של כמה גרסאות של מסמכי תיעוד - עיצובים מותאמים אישית של ממשקי API
יעדי הפרויקט: - שימוש ב-Google Developer Codelabs כדי ליצור מדריכים אינטראקטיביים למשתמשי קצה בנושא SMI ורשתות Service Mesh קשורות, באמצעות Meshery ככלי. - יצירת מדריך למשתמש קצה באמצעות Jekyll לממשקי Service Mesh. - להשתמש ב-Swagger כדי ליצור תיעוד של נקודות קצה ל-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 מתרחבת בקצב מהיר מאוד, הודות לשילוב האחרון שלה כפרויקט Sandbox ב-CNCF. עם זאת, יש בפרויקט מחסור חמור בתיעוד, גם למשתמשי קצה וגם למפתחים. בעבר התנסיתי בממשקי Service Mesh שונים, כולל linkerD עם אפליקציית EmojiVoto, Istio עם אפליקציית bookinfo ו-Consul של Hashicorp. ניסיתי גם לפצל את התנועה ב-SMI והטמעתי כללי אימות שונים בתצורה של service mesh. תהליך הלמידה מרתק, אבל הוא טכני מאוד ויכול להרתיע משתמשים חדשים וגם מפתחים שרוצים לעשות את הצעדים הראשונים בקהילה של service mesh או להשתמש ב-service mesh בפרויקטים אישיים או מקצועיים שלהם. הייתי רוצה לגשר על הפער הזה. את הפער אפשר לעשות רק בעזרת מדריכים ומדריכים יעילים ומתועדים היטב.