בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- ESLint
- כותבים טכניים:
- קוואר
- שם הפרויקט:
- ארגון מחדש או כתיבת מחדש של מסמכי התיעוד בנושא הגדרות
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
מופשט
מטרת הפרויקט היא לשנות את המבנה של מסמכי התצורה של ESLint וליצור ארכיטקטורת מידע יעילה. כך יהיה קל יותר לנווט, וגם נוכל לשפר את נוחות השימוש ואת התועלת של המסמכים.
סיכום הפרויקט במצב הנוכחי, מסמכי התיעוד של הגדרות ESLint (https://eslint.org/docs/user-guide/configuring) מספקים הרבה מידע בדף אחד. למרות שבדף יש כותרות, כותרות משנה ופסקאות מתאימות, יכול להיות שהמסמך יהיה עמוס מדי. אין דרך לנווט לקטע מסוים בדף, וזה מתסכל משתמשים שמתעניינים בקטע מסוים. עקב היעדר הארגון הזה, המידע עלול גם להיאבד, כך שהוא לא ישיג את מטרתו ויבקש מהמשתמשים להשקיע מאמץ נוסף.
עם זאת, אפשר לפתור את הבעיות האלה באמצעות סדרה של שלבים זהירים. כשלב ראשון בארגון מחדש הזה, אני מציע בדיקת תוכן. בדיקת התוכן תעזור לא רק לזהות את הבעיות בהצגת המידע, אלא גם את החסרונות של התוכן עצמו (למשל, מידע לא עדכני או חלקי). לאחר מכן, אעשה שימוש בארכיטקטורת המידע (IA) כדי לחשוף את רשת הידע. כך נוכל לקבץ את המידע לפי נושאים שונים ולמצוא קישורים בין נושאים שונים שקשורים זה לזה. התובנות שמתקבלות משתי השיטות האלה ישמשו לחלוקת התיעוד של הדף היחיד למספר דפים. לאחר מכן אפשר לקשר את החבילה כולה ולהצליב אותה ב-Markdown. כתוצאה מכך, תהיה גרסה מאורגנת יותר של מסמכי ההגדרה, שקל יותר לנווט בה ולהבין אותה.
מוטיבציה למרות שאני משתמש בתוכנות קוד פתוח כבר זמן מה, ההיכרות שלי עם המונח היא חדשה יחסית, בדומה לידע שלי בתוכנות לניפוי שגיאות בקוד (linting). כשהתחלתי ללמוד Python (דרך edX), תהיתי איך שגיאות קטנות יכולות לגרום לכשל בקוד כולו. חשבתי שזה יהיה נחמד לבדוק את הקודים שלך, איכשהו, ולזהות את השגיאות, ואז שמעתי על המונח 'ניפוי שגיאות בקוד'. עדיין לא השתמשתי בתוכנת ניפוי שגיאות בקוד, אבל אני בטוח שהיא תקל עליי מאוד בימים הקרובים.
יש לי רקע בהנדסת חשמל וקצת ניסיון בתכנות, ולכן אני יכולה להבין טוב יותר את בעיות התכנות ואת הדרישות של מתכנתים. בנוסף, התואר שני בתקשורת טכנית ומקצועית עוזר לי לעודד משתמשים, ומנסה להקל על חייהם של אנשים. הכישורים והמומחיות שלי יהיו שילוב טוב לפרויקט הזה, ויוסיפו ערך למסמכי התיעוד של ESLint.
מטרות המטרה הכוללת של הפרויקט היא להבטיח שהמסמכים בדף ההגדרות של ESLint יהיו קלים להבנה ולא יכבידו על המשתמשים. כדי להצליח בפרויקט, חשוב שהניווט בתוכן יהיה קל וללא סיבוכים. היעדים החשובים של הפרויקט הם: - עריכת ביקורת תוכן מקיפה - יצירה של ארכיטקטורת מידע כדי להבין את זרימת המידע - שיפור ארכיטקטורת המידע כדי לארגן מחדש את המסמכים - זיהוי קישורים והפניות בין קטעים שונים בתוכן - שכתוב או עריכה של חלקים במסמך, לפי הצורך כדי לעמוד בדרישות ההגדרה מחדש
- מוודאים שהתוכן גמיש ואפשר לעשות בו שימוש חוזר
תיאור הפרויקט הגדרה של ESLint היא תכונה חשובה שמאפשרת להתאים אישית את ESLint. משתמשים שמתעניינים בהגדרות יהיו בדרך כלל מעוניינים בהיבט אחד או שניים בכל פעם. לכן חשוב להנחות את המשתמש לנושא הספציפי שמעניין אותו, כדי לספק לו את הפתרון בצורה יעילה. המצב הנוכחי של מסמכי התיעוד של ESLint מכיל הרבה מידע שימושי, אבל הוא מאורגן באופן שעלול לגרום למשתמשים להרגיש מוצפים, מתוסכלים או אבודים. לדוגמה, אם מישהו רוצה לדעת איך משתמשים בפלאגינים של צד שלישי ב-ESLint, הוא יצטרך לגלול למטה, לחלק של הדיון על ציון מנתח, סביבות ומשתנים גלובליים. התהליך כולו מעייף את המשתמשים ויכול להרחיק אותם מהאתר. באופן דומה, אם משתמש נמצא באמצע הדף ורוצה לעבור לקטע מסוים או פשוט לעיין בנושאים דומים, המשימה לא תהיה קלה עבורו כי אין למשתמשים עזרה כזו. חשוב לטפל בבעיות האלה באופן מיידי, כי איכות המסמכים, לא משנה כמה הם טובים, תלויה בשימושיותם. בהמשך אציע פתרונות לבעיות האלה ולבעיות קשורות אחרות.
ביקורת תוכן השלב הראשון בתהליך של ארגון מחדש של מסמכי התצורה הוא לבצע ביקורת תוכן מקיפה. מטרת הביקורת היא לזהות כמה בעיות מרכזיות, כמו תוכן לא עדכני, תוכן כפול, תוכן חסר וכו'. גיליון האלקטרוני של ביקורת התוכן שייווצר כתוצאה מכך ישותף עם צוות הניהול וצוות התעודה לקבלת משוב. כך תוכלו לפתח אסטרטגיה חדשה למבנה ולתצוגה של המסמכים.
יצירת ארכיטקטורת מידע כדי להבין את רשת הידע או את זרימת המידע במסמכי התיעוד של ההגדרות, כדאי ליצור ארכיטקטורת מידע (IA). הממצאים של ביקורת התוכן ישמשו כבסיס טוב להבנה ולפיתוח של זרימת המידע. לאחר מכן נוצרת גרסה משופרת של תכנון הממשק כדי לארגן את המסמכים ולהציג אותם בצורה טובה יותר. ה-IA המשופר לא רק יארגן מחדש את התוכן הנוכחי, אלא גם יזהה קישורים והסתעפויות בין קטעים שונים במסמכי העזרה, וכך ייצור רשת יעילה. לדוגמה, אחרי התוכן בקטע 'הגדרת כללים' יכול להופיע קישור שמוליך לקטע 'השבתה של כללים באמצעות תגובות בתוך הטקסט'. אפשר לזהות גם קישורים אחרים כאלה, וכך ליצור קשרים בין קטעים שונים במסמכי העזרה.
תוכן עניינים: בדיקת התוכן וה-IA יספק מידע מספיק כדי ליצור תוכן עניינים מפורט עם קישורים לקטעים ולקטעים משנה ספציפיים במסמכי התיעוד. יצירת קבצים נפרדים לכל קטע והוספת הפניות מתאימות לחלקים אחרים, יכולים להוסיף ערך לכל קבוצת המסמכים. אפשר ליצור תוכן מפורט למשתמשים שמגיעים למסמכי ההגדרה, כדי לעזור להם במהלך הביקור באתר. תוכן העניינים יכול לכלול את כל הכותרות ברמה הראשונה והשנייה כדי שהוא יהיה קצר אך מקיף. אחת השיטות האלה, למשל, היא ש-Prettier (https://prettier.io/docs/en/index.html ) משתמשת ב-Prettier.io/docs/en/index.html כדי לארגן את התיעוד.
כל מסמכי התיעוד ייווצרו באמצעות Markdown כדי לשמור על דברים פשוטים ומאורגנים היטב. ייעשה מאמץ מיוחד כדי להבטיח שניתן יהיה לעשות שימוש חוזר במסמכים, מאחר שהמסמכים עשויים לגדול ולהשתנות בעתיד.
כלים לשימוש כמה כלים חשובים שיכולים להועיל לכם בעבודה על הפרויקט הם: - Draw.io ליצירת איורים ל-IA לפי הצורך - Atom (או עורך דומה) לכתיבה ולעריכה של מסמכים ב-Markdown
- GitHub כדי להבטיח ניהול גרסאות של המסמכים
אבני דרך משליחת ההצעה ועד להשלמת הפרויקט, אבני הדרך החזויות הבאות יבטיחו שהפרויקט יסתיים בזמן, תוך שמירה על התהליך הנכון בתהליך.
10 ביולי 2020 עד 16 באוגוסט 2020: בדיקה ובחירה של הצעות: אקרא את מסמכי התיעוד של ESLint ואפתח את הכישורים הנדרשים כדי להשלים את הפרויקט (כמו כתיבת Markdown, עבודה משותפת ב-GitHub). אני גם אשתתף במסמכי העזרה דרך GitHub ואשתף את הידע שלי עם אנשים אחרים כדי להבין טוב יותר את המסמכים.
17 באוגוסט 2020 עד 13 בספטמבר 2020: יצירת קשרים עם הקהילה במהלך תקופת גיבוש הקהילה, אשפר את ההצעה שלי בהתאם לדיונים עם החונכים והצוותים האחראים. אערוך גם את היעדים ואת אבני הדרך, אם יהיה צורך. בנוסף, אעשה רשימה של הכלים שבהם נשתמש בפרויקט.
14 בספטמבר 2020 עד 19 בספטמבר 2020: ביקורת תוכן כדי להתחיל את הפרויקט, אבדוק את תוכן המסמכים של ההגדרות באופן מקיף. המטרה היא להדגיש בעיות בתוכן ובאופן הצגתו.
20 בספטמבר 2020 עד 25 בספטמבר 2020: ארכיטקטורת מידע (IA) לאחר ביקורת התוכן, אצור את ה-IA של מסמכי התצורה. אנסה להציג את רשת הידע בצורה מובנת. כך נוכל לשפר את זרימת המידע.
26 בספטמבר 2020 עד 30 בספטמבר 2020: קישורים והפניות אנתח את תכנון הממשק במהלך השלב הזה כדי למפות קישורים והפניות בין קטעים שונים במסמכי העזרה. בנוסף, אצור היררכיה של כל הקטעים, וכך אשתפר את תכנון ממשק המשתמש בתהליך.
1 באוקטובר 2020 עד 3 באוקטובר 2020: המפה הסופית בעזרת התובנות שקיבלתי מבדיקת התוכן ומניתוח ה-IA, אצור מפה סופית שתוטמע במסמכי ההגדרה המאורגנים מחדש. המפה המקיפה הזו תכלול תוכן עניינים, היררכיית נושאים ורשימה של קישורים והפניות בין קטעים במסמכי העזרה.
4 באוקטובר 2020 עד 5 באוקטובר 2020: דיון בשלב הזה, לפני עריכת המסמכים, אציג את הממצאים והתוכנית שלי למנטורים ולצוותים הרלוונטיים. המשוב שלהם יעזור לכם לשפר את התוכנית ולבצע שינויים במקרים הנדרשים.
6 באוקטובר 2020 עד 20 באוקטובר 2020: כתיבת מחדש ועריכה במהלך התקופה הזו אערוך ואעדכן את החלקים במסמכים שצריך לעבוד עליהם. יכול להיות שחלק מהקטעים במסמכי העזרה בנושא הגדרות ייכתבו מחדש או שיתווספו להם דברים חדשים. המיקוד בשלב הזה יהיה להבטיח שהמסמכים יהיו מדויקים, מעודכנים, גמישים וניתן לעשות בהם שימוש חוזר.
21 באוקטובר 2020 עד 25 באוקטובר 2020: תיקונים וקישורים בשלב הזה אבדוק את העבודה שלי כדי להסיר שגיאות דקדוקיות ומבניות, וגם כדי לוודא שהיא מדויקת. אוסיף גם קישורים והפניות בין קטעים, בהתאם לתכנון הארכיטקטוני, כדי לוודא שהמסמכי העזרה עומדים בדרישות של מפת הידע שפיתחנו קודם.
26 באוקטובר 2020 עד 31 באוקטובר 2020: הגרסה הסופית לשליחה אקשר את כל קובצי ה-Markdown, אצור תוכן עניינים ואשתף את הטיוטים עם המנטורים. זה יהיה טופס השליחה של הטיוטה הראשונה, כחבילה מלאה.
1 בנובמבר 2020 עד 5 בנובמבר 2020: בדיקה ראשונית במהלך חמשת הימים האלה, אדבר על הטיוטה הראשונה עם המנטורים שלי. אקבל מהם משוב ואדון איתם ברעיונות שלי כדי ליצור רשימה של שינויים שצריך לבצע.
6 בנובמבר 2020 עד 12 בנובמבר 2020: עריכות ראשונות בעזרת המשוב של המנטורים, אערוך את הטיוטה הראשונה של המסמך. העריכות בפועל יהיו תלויות באופי התגובות והמשוב, אבל המטרות של שימוש חוזר, דיוק וגמישות יהיו מוקד שלב העריכה.
13 בנובמבר 2020 עד 15 בנובמבר 2020: בדיקה שנייה לאחר השלמת העריכה הראשונית, אדבר שוב עם המנטורים שלי ועם הצוותים הרלוונטיים על ההתקדמות. הדיונים האלה יתמקדו בשינויים שבוצעו בגרסה הראשונה, וגם יצביעו על בעיות אחרות שעשויות להתעורר בתהליך העריכה.
16 בנובמבר 2020 עד 19 בנובמבר 2020: עריכות שנייה לאחר מכן אקדיש ארבעה ימים לעריכת המסמך. הגרסאות שייווצרו כתוצאה מכך ידונו עם המנטורים כדי לתת להן צורה סופית. בסיום השלב הזה, המסמכים יהיו בצורתם הסופית ויהיה אפשר להעלות אותם לאתר ולמאגר GitHub.
20 בנובמבר 2020 עד 23 בנובמבר 2020: העלאה לאתר אחרי ביצוע כל העריכות הנדרשות, המסמכים יועלו לאתר. נתייחס לכל בעיה שתתגלה בתהליך בהתאם, כי עדיין יהיו לנו כמה ימים לעבוד על המסמכים.
24 בנובמבר 2020 עד 28 בנובמבר 2020: דוח פרויקט במהלך חמשת הימים האלה נוצר דוח מפורט של הפרויקט. היעדים, הקשיים, הבעיות והפתרונות שיוצגו יהיו חלק מדוח הפרויקט. הדוח ישותף עם המנטורים לצורך משוב.
29 בנובמבר 2020 עד 30 בנובמבר 2020: הגשה סופית של הפרויקט יחד עם כל הקבצים ודוח הפרויקט יישלח לחונכים. הבדיקה של הפרויקט כולו תתבצע במהלך פגישה או דיון עם המנטורים והצוותים הרלוונטיים.
לאורך הפרויקט, אמשיך להתייעץ עם המנטורים כדי לקבל משוב חשוב מהם. אפשר לשנות את כל אבני הדרך האלה על סמך הדיונים עם המנטורים בתקופות של יצירת הקשר עם הקהילה ובדיקת ההצעה.
מידע עליי יש לי תואר ראשון בהנדסת חשמל ותואר שני בתקשורת טכנית ומקצועית מאוניברסיטת צפון קרולינה. יש לי ניסיון בתחומים של כתיבה ועריכה טכנית ומקצועית, תקשורת וניהול תוכן, מחקרים בנושא נוחות השימוש באינטרנט ובנייד ועיצוב הנחיות. עבדתי כעורכת משנית במגזין אונליין (Global Village Space) וכמתמחה בתקשורת ב-Duke Forge באוניברסיטת Duke. בנוסף, יש לי עניין בכתיבה יוצרת.