דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- gRPC-Gateway
- כתב טכני:
- iamrajiv
- שם הפרויקט:
- ארגון מחדש של אתר Docs הקיים של gRPC-Gateway
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
מופשט:
האתר של מסמכי המשתמש נועד לעזור למשתמשי קצה להשתמש במוצר או בשירות. האתר הטוב של מסמכי המשתמש חשוב מאוד מכיוון שהוא מספק למשתמשים דרך ללמוד כיצד להשתמש בתוכנה, בתכונות, בטיפים ובטריקים שלה, וכן לפתור בעיות נפוצות בעת השימוש בתוכנה. בנוסף, השירות מפחית את עלות התמיכה והוא חלק מהזהות הארגונית של המוצר. אתר טוב של מסמכי משתמשים הוא סימן לתקינות של המוצר, צוות המפתחים. ללא אתר טוב של מסמכי משתמשים, ייתכן שמשתמש לא יידע איך לבצע את הפעולות שלמעלה בצורה יעילה ויעילה. אתרים של מסמכי משתמשים יכולים למלא תפקיד מרכזי בהבטחת ההצלחה של מוצר, מכיוון שתקשורת נהדרת היא העיקרון המנחה של כל עסק או מוצר, והתיעוד הנהדר פשוט לוקח את התקשורת ומציב אותה במסגרת ניתנת לניהול שאליה כל אחד יכול לגשת להצלחה.
נכון למועד כתיבת הנתונים האלה, המאגר של gRPC-Gateway חולל כ-1,200 פעמים. כ-184 אנשים תרמו למאגר. זה מראה שאנשים רבים בכל העולם משתמשים ב-gRPC-Gateway וכדאי להם לקרוא את התיעוד למשתמשים שלו כדי לקבל הנחיות לשימוש ב-gRPC-Gateway. עם זאת, אתר התיעוד והמסמכים למשתמש של gRPC-Gateway מיושן ואינו שלם כרגע, וקהילת gRPC-Gateway רוצה להשתמש בפרויקט הזה כדי לסדר מחדש את אתר המסמכים הקיים כדי לשפר את אתר המסמכים שלו ולאפשר למשתמשי קצה ליהנות מחוויה חלקה כשהם משתמשים ב-gRPC-Gateway.
המצב הנוכחי:
כרגע, באתר המסמכים של gRPC-Gateway יש שתי בעיות עיקריות:
• הבעיה הראשונה היא אתר מסמכים פגום ומיושן, עם העיצוב והמבנה של האתר והעיצוב שבשימוש מיושן, חלקי, קשה לניווט או לאיתור מידע, ולא מכסה תכונות רבות של אתרי מסמכים טובים. ארגון מחדש של אתר Docs הקיים של gRPC-Gateway יכלול עיצוב אתר, הוספת תכונות כמו חיפוש מסמכים וכו', שיפור ממשק המשתמש של האתר, ארגון מדריכים ודוגמאות בסרגל צד מתאים ועדכון תרשימי הזרימה והתמונות הקיימים על ידי עיצוב חדש ועוד. זו תהיה המטרה העיקרית שלי, ואעבוד על העיצוב והשינוי של מבנה האתר ב-Docs.
• הבעיה השנייה היא צורך לארגן מחדש את התיעוד, המדריכים והדוגמאות הקיימים וכו' של gRPC-Gateway. כך ניתן לעשות זאת על ידי הסרת טעויות טיפוגרפיות ודקדוקיות בכל הקבצים, התאמה נכונה של קטעי הקוד של Go ויצירה מחדש של קטעי קוד של Go בהתאם לפורמטים של Goppt. בנוסף, אם יהיה צורך, נוכל להוסיף עוד מסמכים, מדריכים ודוגמאות במקרה הצורך, או להשתמש שוב בקבצים הקיימים לאחר ארגון הקוד מחדש (Refactoring). זו המטרה המשנית שלי ואעשה זאת לאחר שאסיים את המטרה העיקרית שלי, כלומר עיצוב ובנייה מחדש של אתר Docs הקיים.
למה האתר שהצעתי כרגע הוא שיפור על פני האתר הנוכחי?
האתר של מסמכי המשתמש ייבנה כדי לשפר ולהבטיח יעילות, עקביות ושקט נפשי עבור משתמש הקצה. הוא יעניק מראה טוב יותר וממשק משתמש עם קטעים מעוצבים היטב ותכונות הכוללות מדריכים כתובים ותרשימי זרימה ותמונות המשויכים אליהם.
התיעוד של gRPC-Gateway מספק תיאור טוב של השיטה ודוגמה. אבל הוא עדיין משתמש בעיצוב של Jekyll הישן ובימים המודרניים יש לנו עיצובי Jekyll טובים יותר ב-SSG (מחולל אתרים סטטיים). בנוסף, יש צורך בשינוי מבנה הדפים כדי שיהיה שימושי יותר למשתמשים על ידי הוספה של דוגמאות ומדריכים חדשים, וגם עדכון ושכתוב של התכנים הקודמים.
המבנה ומפת הדרכים של היעדים והרעיונות המוצעים:
היעד העיקרי של פרויקט זה:-
ניתן ליישם את היעדים והרעיונות שמופיעים למעלה בדרכים הבאות:-
החלפת העיצוב שלCurrent Jekyll לעיצוב טוב וחזק. הסיבה לשימוש חוזר בעיצובים של Jekyll היא שיהיה קל יותר למנהלים לתרום ולהבין את תהליך העבודה של הפרויקט, מכיוון שהם כבר מודעים ל-framework ולעיצוב הקיימים של Jekyll, שדומה לעיצוב החדש של Jekyll.
עברתי על עיצובים שונים של Jekyll באינטרנט ומצאתי את https://idratherbewriting.com/document-theme-jekyll/ חבילה העיצובים הזו עבור אתר המסמכים של gRPC-Gateway, בגלל התכונה הבאה:
• Markdown:- כך שכותבים טכניים לא יצטרכו לדאוג להתקנה. הם יכולים לכתוב פשוט בקובץ ה- .md. כל אחד יכול ללחוץ על לחצן העריכה שמוצג באתר (תכונה חדשה) ולתרום (לערוך/להציע שינויים לדף ב-GitHub) כדי לשפר אותו. הפעולה הזו תעודד את המשתמשים להוסיף תוכן חדש או לערוך תוכן כדי לשפר אותו.
• חיפוש מסמכים:- למשתמש צריכה להיות תיבת חיפוש, כדי שיוכלו למצוא תוכן רלוונטי בקלות ובמהירות.
• הקטע 'תגובות':- ייתכן שלמשתמש תהיה אפשרות להגיב ולשתף את הדעות שלו בפוסטים ובמדריכים. הם יכולים לקרוא צפיות של אנשים אחרים בתיעוד הפרויקט.
• הערות מוצר ובלוגים חדשים: האתר אמור להתעדכן בפוסטים חדשים בבלוגים וחדשות על הפיתוח הנוכחי ומפת הדרכים. לכן, סוג של בלוג צריך להופיע בדף הנחיתה.
• פיתוח מהיר:- רוב המסגרות מסוג SSG (Static Site Generator) פועלות בשרת והשינויים בקובץ באים לידי ביטוי בממשק המשתמש באופן מיידי. בנוסף, תהליך הפריסה והבנייה צריך להיות קל. בעתיד, אם נרצה לשנות את המסגרת, נשתמש בה. לאחר מכן זה אמור להיות קל. רוב המסגרות תומכות בכתיבה ב-Markdown, לכן צריך רק להעביר את קובצי ה- .md ולבצע מעט שינויים.
בדוגמה הזו אני מפצל את דפי האתר הקיימים לחלקים ולדפים חדשים באתר :
• דף נחיתה:-
בדף הנחיתה צריך לציין את התכונות העיקריות של gRPC-Gateway.
- תחילת העבודה עם gRPC-Gateway (הפניה למדריך למשתמש)
- הוראות התקנה פשוטות (פקודות קצרות)
- למה כדאי להשתמש ב-gRPC-Gateway
- פרויקט באמצעות gRPC-Gateway
לכן הרעיון הבסיסי הוא במקום לכתוב תיאור ארוך, להציג את הנקודות העיקריות בדף הנחיתה ולספק את הקישור שמוביל לפרטים.
• דף המדריך למשתמש של gRPC-Gateway:
- מדריך התקנה.
- התחלה מהירה עם gRPC-Gateway.
• דף המדריך למפתחים של gRPC-Gateway:-
מדריך פיתוח, מדריך לתרומות, הגדרת Git, קוד התנהגות, הגדרת תיעוד, תהליך פיתוח וכו' מפנים לדפים דומים בפנים. לכן יש צורך בארגון כל הקבצים מחדש. דף הפיתוח הראשי צריך להכיל את כל הדפים האלה, וההיפר-קישור ייווצר בכל שלב.
• מידע על הדף 'gRPC-Gateway':
רשימת כל המשתתפים צריכה להופיע בקטעים של הצוות קישורים מהירים והודעות לגבי המוצר, יתווספו לבלוגים האחרונים כדי לעודד את המשתמשים לקרוא על החדשות הנוכחיות ב-gRPC-Gateway.
• דף בלוגים, הערות מוצר ומדריכים:-
לדעתי אמורה להיות באתר אפשרות של כתיבת בלוג. כך שניתן להעביר בקלות חדשות ופרסומים. דף המדריך יכלול כמה הרצאות ומאמרים פופולריים שמבהירים את ממשקי ה-API והמושגים של gRPC-Gateway. בעלי הרשאת עריכה יכולים להוסיף קישורים למדריך בדף ההדרכה.
אחרי שמשלימים את המשימה שלמעלה, צריך לעדכן את אותם שינויים בהסתעפות v2 ולבצע גם עם ההסתעפות הראשית של gRPC-Gateway.
יעד משני של פרויקט זה:-
יש לבצע שינויים אחרים כדי שהתיעוד של gRPC-Gateway יהיה אמין וקריא יותר:
• תיקון שגיאות דקדוק ושגיאות טיפוגרפיות וארגון ויישור של קישורים ופוסטים באתר בכל הקבצים הקיימים של gRPC-Gateway.
• אם יש צורך ב-gRPC-Gateway, כדאי להוסיף עוד תיעוד ותוכן ב-gRPC-Gateway, מאחר שלרוב התכונות יש תיעוד קצר מאוד. לדוגמה, בקטע Documents של האתר ב-AWS, ברקע ובשימוש וכו'.
• ארגון מחדש של קטעי קוד של Go gRPC-Gateway בהתאם לפורמטים של Gotmt
אחרי שמשלימים את המשימה שלמעלה, צריך לעדכן את אותם שינויים בהסתעפות v2 ולבצע גם עם ההסתעפות הראשית של gRPC-Gateway.
למה אני האדם המתאים בפרויקט הזה:
אני מאמין שאני האדם הנכון לפרויקט הזה כי:-
• יש לי ניסיון רב בשיפור התיעוד של ארגונים, ואני יכול להשתמש בכל מערכת לניהול גרסאות, כך שביצוע פקודות ב-GitHub לא יהיה בעיה. • בנוסף, מה שמניע אותי הוא לעבוד על פרויקטים בעלי ערך לאנשים. אם אתם רוצים שמישהו יעשה משהו בצורה היעילה ביותר, אתם מתעדים אותו. תיעוד התהליכים שלכם מבטיח יעילות, עקביות ושקט נפשי לכל המעורבים. • תהליך העבודה ו-codebase של gRPC-Gateway מוכרים לי כי הצטרפתי ל-gRPC-Gateway מהחודשיים האחרונים ומוזגו 11 PR.