פרויקט Cloud Native Computing Foundation (CNCF)

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

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

ארגון קוד פתוח:
Cloud Native Computing Foundation‏ (CNCF)
כותבים טכניים:
סיאם סונדאר ק
שם הפרויקט:
דוגמאות נוספות וטובות יותר ל-Kubectl
אורך הפרויקט:
אורך סטנדרטי (3 חודשים)

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

מטרת הפרויקט היא לשפר את המדריך הקצר הקיים ל-kubectl ואת מסמכי העזרה.

אלה היעדים העיקריים של הפרויקט: • יצירת דוגמאות נוספות וטובות יותר ל-kubectl. • הוספת דוגמאות ל-kubectl למסמך ה-cheat sheet של kubectl. • שינוי מבנה של מסמכי kubectl כדי להפוך אותם למועילים ככל האפשר.

יעד 1 – דוגמאות ל-kubectl:

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

יעד II – שיפור התועלת מהמסמכים:

כדי שהמסמכים יהיו מועילים יותר, אפשר:

• ביטול קשיים של מתחילים • סידור מחדש של פקודת ה-kubectl בסדר מסוים כדי להבטיח את ההמשכיות בתהליך הלוגי.

הסברים טובים יותר על פקודות או על תרחישי שימוש יעזרו למתחילים להבין את הנושא. זה אולי נשמע פשוט, אבל יכולה להיות לכך השפעה משמעותית על אנשים מתחילים, שיכולים להמשיך ללמוד או להפסיק. נניח, למשל, כשהתחלתי עם kubernetes דרך kubectl, לא הייתי בטוח מה ההבדלים בין Pods לבין פריסות. בהתחלה פרסתי שירות לקצה העורפי שנכתב ב-Nodejs. אחרי כמה שעות רציתי להפסיק את הפעולה, ולכן ניסיתי למחוק את ה-pod, אבל בגלל היכולת של ה-pods לתקן את עצמם, הם נוצרו מחדש. לא היה לי ברור מה קורה, ותהיתי למה יוצרים אותו מחדש ולא נמחקים. אחרי כמה חיפושים באינטרנט הבנתי שמחיקת פקעות היא לא זהה למחיקת פריסה. בעיניים מנוסות זה עשוי להיראות פשוט, אבל הסבר ברור שמבטל את הסוגים האלה של אי-בהירות הוא מה שמבדיל בין מסמך טוב למסמך מצוין.

סידור מחדש של פקודת kubectl בסדר מסוים כדי להבטיח המשכיות בזרימה הלוגית. אם אתם כמוני, מאמינים מאוד בסיפורת, סביר להניח שתתהו איך אפשר להוסיף אלמנטים של סיפורים גילוי לב לגיליון של מסמך שמכיל רשימה של פקודות מסוף. אני אומר, אפשר לעשות את זה. לכל דבר שאנחנו לומדים יש תמיד זרימה לוגית – נקודת התחלה ונקודת סיום, אם תרצו. כמו כל כלי שורת פקודה, ל-Kubectl יש עקומת למידה. למעשה, עקומת הלמידה שלו תואמת לעקומת הלמידה של Kubernetes עצמו. כמעט כולם מתחילים את הדרך שלהם עם Kubernetes דרך kubectl (חוץ מהאנשים שמשתמשים בממשק המשתמש באינטרנט), וגם כי עקומת הלמידה של kubectl קשורה מאוד לעקומת הלמידה של Kubernetes, אפשר לשפר את המסמכים באופן משמעותי רק על ידי שינוי הסדר של הפקודות האלה והוספת אלמנטים של סיפורים. לדוגמה, אפשר להסביר תכונות כמו התאמה אופקית של קבוצות Pod לעומס אחרי שמסבירים על המשאבים באמצעות דוגמאות ואיורים מהעולם האמיתי.

יעד 3 – שיפורים בנוחות השימוש ב-Docs:

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

הנה כמה שינויים שאני ממליץ לבצע:

• גלילה אוטומטית של חלונית הצד ימין לקטע הפעיל הנוכחי במסמכים הראשיים – התכונה הזו יכולה לעזור לכם לעקוב אחרי הקטעים הנוכחיים, העתידיים והקודמים. • העתקה ללוח העריכה – חלק מהפקודות יכולות להיות ארוכות, והפונקציונליות של ההעתקה יכולה להיות שימושית כשעובדים עם פקודות מהסוג הזה. • עיצוב התוכן של קובצי doc – אחרי ההעברה, התוכן בדפים מסוימים לא מעוצב בצורה תקינה. לדוגמה: הקטע Resource Type (סוג המשאב) בסקירה הכללית של kubectl. הפעולה הזו פוגעת בחוויית המשתמש.

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