בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון בקוד פתוח:
- gRPC-Gateway
- כותבים טכניים:
- iamrajiv
- שם הפרויקט:
- שינוי מבנה של אתר התיעוד הקיים של gRPC-Gateway
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
תקציר:
אתר המסמכים למשתמש נועד לעזור למשתמשי הקצה להשתמש במוצר או בשירות. אתר מסמכי העזרה למשתמשים חשוב מאוד כי הוא מספק למשתמשים דרך ללמוד איך להשתמש בתוכנה, להכיר את התכונות שלה, לקבל טיפים וטריקים וגם לפתור בעיות נפוצות שנתקלים בהן בזמן השימוש בתוכנה. בנוסף, היא מפחיתה את עלויות התמיכה והיא חלק מהזהות הארגונית של המוצר. אתר מסמכי העזרה הטוב למשתמש הוא סימן לבריאות המוצר, לצוות הפיתוח. בלי אתר טוב של מסמכי עזרה למשתמשים, יכול להיות שהמשתמשים לא ידעו איך לבצע את הפעולות שלמעלה בצורה יעילה. אתר מסמכי התיעוד של המשתמש יכול למלא תפקיד מרכזי בהבטחת הצלחה של מוצר כי תקשורת טובה היא תמיד הבסיס של כל עסק או מוצר, ותיעוד מעולה פשוט לוקח את התקשורת הזו ומציב אותה במסגרת שניתנת לניהול, שכולם יכולים לגשת אליה כדי להצליח.
נכון למועד כתיבת שורות אלה, המאגר של gRPC-Gateway עבר כ-1,200 פעמים פורק (fork) ו-184 אנשים תרמו למאגר הזה. הנתונים האלה מראים שאנשים רבים ברחבי העולם משתמשים ב-gRPC-Gateway, ויכול להיות שכדאי לכם לקרוא את מסמכי התיעוד של המשתמשים כדי לקבל הנחיות לשימוש ב-gRPC-Gateway. עם זאת, מסמכי התיעוד והאתר של gRPC-Gateway לא מעודכנים וערוכים באופן חלקי. קהילת gRPC-Gateway רוצה להשתמש בפרויקט הזה כדי לשפר את אתר המסמכים הקיים, כדי לאפשר למשתמשי הקצה ליהנות מחוויית שימוש חלקה ב-gRPC-Gateway.
המצב הנוכחי:
נכון לעכשיו, באתר מסמכי gRPC-Gateway יש שתי בעיות עיקריות:
• הבעיה הראשונה היא אתר Docs פגום ומיושן, שמציג את העיצוב והמבנה של האתר והעיצוב שבו נעשה שימוש מיושן, לא שלם, קשה לניווט או למצוא מידע, לא כולל הרבה תכונות של אתר טוב של Docs. ארגון מחדש של האתר הקיים ב-Docs של gRPC-Gateway יכלול עיצוב של האתר, הוספת תכונות כמו חיפוש במסמכים וכו', שיפור ממשק המשתמש של האתר, ארגון מדריכים ודוגמאות בסרגל צד מתאים ועדכון תרשימי הזרימה והתמונות הקיימים על ידי עיצוב תמונה חדשה וכו'. זה יהיה היעד העיקרי שלי, והעבודה שלי תתבסס על עיצוב ובנייה מחדש של אתר Docs קיים.
• הבעיה השנייה: יש צורך לבצע רפאקציה של המסמכים הקיימים, המדריכים, הדוגמאות וכו' של gRPC-Gateway. אפשר לעשות זאת על ידי הסרת שגיאות דפוס ודקדוק בקבצים, התאמה נכונה של קטעי הקוד ב-Go וביצוע רפאקציה של קטעי הקוד ב-Go בהתאם לפורמטים של Gofmt. בנוסף, אם כן, נוכל להוסיף מסמכי עזרה, מדריכים ודוגמאות לפי הצורך, או שנוכל לעשות שימוש חוזר בקבצים הקיימים אחרי שנעשה להם רפאקציה. זו המטרה המשנית שלי, שאעשה זאת לאחר שאסיים את המטרה העיקרית שלי, כלומר עיצוב וסידור מחדש של האתר הקיים ב-Docs.
למה האתר החדש של המסמכים עדיף על האתר הנוכחי?
האתר המוצע למסמכי התיעוד של המשתמשים יותאם כך שישפר את היעילות, העקביות והשקט הנפשי של משתמשי הקצה. המראה של האתר וממשק המשתמש שלו ישתפרו, עם קטעים ותכונות מסוגננים שמכילים מדריכים כתובים, תרשימי זרימה ותמונות שמשויכים אליהם.
במסמכי התיעוד של gRPC-Gateway יש תיאור טוב של השיטה והדוגמה. אבל עדיין נעשה בו שימוש בנושא Jekyll ישן, ובימינו יש לנו נושאי Jekyll טובים יותר ל-SSG (כלי ליצירת אתרים סטטיים). בנוסף, יש צורך לבצע שינוי מבני בדפים ולהפוך אותם למועילים יותר למשתמשים על ידי הוספת דוגמאות ומדריכים חדשים ועדכון וכתיבה מחדש של התוכן הקודם.
המבנה והתוכנית של היעדים והרעיונות המוצעים:
היעד הראשי של הפרויקט הזה:-
אפשר ליישם את היעדים והרעיונות שלמעלה בדרכים הבאות:
העברת העיצוב הנוכחי של Jekyll לעיצוב טוב יותר ויציב יותר. הסיבה לשימוש שוב בנושאי Jekyll היא שקל למנהלי הפרויקטים לתרום ולהבין את תהליך העבודה בפרויקט, כי הם כבר מכירים את המסגרת והנושא הקיימים של Jekyll, שדומים לנושא החדש של Jekyll.
בדקתי נושאים שונים של Jekyll באינטרנט, ומצאתי שחבילה זו של נושאים https://idratherbewriting.com/documentation-theme-jekyll/ מתאימה ביותר לאתר המסמכים של gRPC-Gateway בגלל התכונה הבאה:
• Markdown:- כך שכותבי מאמרים טכניים לא יצטרכו לדאוג להתקנה. הם יכולים לכתוב בקלות בקובץ ה- .md. כל אחד יכול ללחוץ על לחצן העריכה שמוצג באתר (תכונה חדשה) ולתרום (לערוך או להציע שינויים בדף ב-GitHub) כדי לשפר אותו. כך תוכלו לעודד משתמשים להוסיף תוכן חדש או לערוך תוכן כדי לשפר אותו.
• חיפוש מסמכי עזרה:- המשתמשים צריכים לקבל תיבת חיפוש כדי שיוכלו למצוא תוכן רלוונטי בקלות ובמהירות.
• הקטע 'תגובות': המשתמש יכול להגיב ולשתף את התגובות שלו בפוסטים ובמדריכים. הם יכולים לקרוא את הדעות של אנשים אחרים לגבי מסמכי הפרויקט.
• נתוני גרסה חדשים ופוסטים חדשים בבלוג:- האתר צריך להתעדכן בפוסטים חדשים בבלוג ובחדשות על הפיתוח הנוכחי ועל תוכנית העבודה. לכן, כדאי לכלול בדף הנחיתה פוסט בבלוג.
• פיתוח מהיר: רוב המסגרות של ה-SSG (Static Site Generator) פועלות בשרת, ושינויים בקובץ משתקפים באופן מיידי בממשק המשתמש. בנוסף, תהליך הפריסה וה-build צריכים להיות קלים. בעתיד, אם נרצה לשנות את המסגרת, נשתמש. לאחר מכן, זה אמור להיות קל. רוב המסגרות תומכות בכתיבה ב-Markdown, כך שפשוט העברת קובצי ה- .md וביצוע כמה שינויים אמורים להספיק.
כאן אני מפצל את דפי האתר הקיימים לקטעים ולדפים חדשים באתר :
• דף נחיתה:-
בדף הנחיתה צריך לציין את התכונות העיקריות של gRPC-Gateway.
- תחילת העבודה עם gRPC-Gateway (הפניה אוטומטית למדריך למשתמש)
- הוראות התקנה פשוטות (פקודות קצרות)
- למה כדאי להשתמש ב-gRPC-Gateway
- פרויקט שמשתמש ב-gRPC-Gateway
לכן, הרעיון הבסיסי הוא במקום לכתוב תיאור ארוך, להציג את הנקודות העיקריות בדף הנחיתה ולספק את הקישור לפרטים.
• דף המדריך למשתמש של gRPC-Gateway:-
- מדריך התקנה.
- תחילת העבודה עם gRPC-Gateway.
• דף המדריך למפתחים בנושא gRPC-Gateway:-
הדפים Development Guide, Contribution guide, Git setup, Code of Conduct, Documentation setup, Development workflow וכו' מפנים לדפים דומים בתוך הספרייה. לכן צריך לבצע רפגורמציה ולסדר מחדש את כל הקבצים. הדף הראשי של הפיתוח צריך להכיל את כל הדפים האלה, וההיפר-קישור ייווצר בכל שלב.
• מידע על הדף gRPC-Gateway:-
רשימת כל התורמים צריכה להופיע בקטעי הצוותים. יוצגו גם קישורים מהירים ותיאורי גרסאות, וכן הבלוגים האחרונים כדי לעודד את המשתמשים לקרוא על החדשות הנוכחיות בנושא gRPC-Gateway.
• דף של בלוגים, נתוני גרסה ומדריכים:-
לדעתי, האתר צריך לכלול אפשרות לכתיבה בבלוג. כך אפשר להעביר בקלות חדשות ופרסומים. דף המדריך יכלול כמה הרצאות ומאמרים פופולריים שיבהירו את המושגים וממשקי ה-API של gRPC-Gateway. שותפים ביצירת התוכן יכולים להוסיף את הקישורים למדריכים שלהם בדף המדריכים.
אחרי השלמת המשימה שלמעלה, מעדכנים את אותם שינויים בהסתעפות v2 ומבצעים אותם גם בהסתעפות master של gRPC-Gateway.
היעד המשני של הפרויקט הזה:-
יש לבצע שינויים נוספים כדי שהמסמכי התיעוד של gRPC-Gateway יהיו עמידים וקריאים יותר:-
• תיקון שגיאות דקדוק וטיפוגרפיות וארגון הקישור והפוסטים באתר בכל הקבצים הקיימים של gRPC-Gateway.
• הוספת מסמכי עזרה ותוכן לפי הצורך ב-gRPC-Gateway, כי לרוב התכונות יש מסמכי עזרה קצרים מאוד, כמו בקטע 'מסמכי עזרה' באתר של AWS, 'רקע' ו'שימוש' וכו'.
• ארגון מחדש של קטעי הקוד של Go מ-gRPC-Gateway בהתאם לפורמטים של GoFMt
אחרי שתשלימו את השלבים שלמעלה, עדכנו את אותם שינויים בהסתעפות v2 ומבצעים גם את ההסתעפות הראשית של gRPC-Gateway.
למה אני המועמד המתאים לפרויקט הזה:
לדעתי אני האדם המתאים לפרויקט הזה כי:-
• יש לי ניסיון בעבר בשיפור מסמכי התיעוד של ארגונים, ואני יכול להשתמש בכל מערכת לניהול גרסאות, כך שאין לי בעיה לבצע פקודות ב-GitHub. • בנוסף, מה שמניע אותי הוא עבודה על פרויקטים שמניבים ערך לאנשים. לדעתי אם רוצים שמישהו יבצע פעולה כלשהי באופן היעיל ביותר, עליך לתעד זאת. תיעוד התהליכים מבטיח יעילות, עקביות ושקט נפשי לכל מי שמעורב. • אני מכיר את תהליך העבודה ואת קוד המקור של gRPC-Gateway כי אני תורם ל-gRPC-Gateway בחודשיים האחרונים, ו-11 בקשות המיזוג שלי אוחדו.