דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- ESLint
- כתב טכני:
- חוואר
- שם הפרויקט:
- ארגון מחדש/שכתוב של מסמכי התיעוד בנושא הגדרות אישיות
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
מופשט
מטרת הפרויקט היא לבנות מחדש את תיעוד ההגדרות עבור ESLint וליצור ארכיטקטורת מידע יעילה. הפרטים האלה יקלו על הניווט וישפרו את נוחות השימוש והיעילות של התיעוד.
סיכום פרויקט תיעוד ההגדרה של ESLint (https://eslint.org/docs/user-guide/configurs) במצב הנוכחי מספק מידע רב בדף אחד. למרות נוכחותם של כותרות, כותרות משנה ופסקאות מתאימות בדף, התיעוד עלול להיות מבלבל. אין דרך לנווט לקטע מסוים בדף, וזה מתסכל משתמש שמתעניין בחלק מסוים. בגלל היעדר הארגון הזה, המידע עלול גם ללכת לאיבוד, לא לשרת את מטרתו ולבקש מהמשתמשים להשקיע מאמץ נוסף.
עם זאת, ניתן לפתור בעיות אלה באמצעות סדרה של צעדים זהירים. ההצעה שלי היא לבצע בדיקת תוכן כשלב הראשון בארגון הזה. ביקורת תוכן לא רק תעזור בזיהוי הבעיות בהצגת המידע, אלא גם תדגיש את החסרונות של התוכן עצמו (למשל, מידע מיושן או חלקי). לאחר מכן אני מתכנן ליצור את ארכיטקטורת המידע (IA) כדי לחשוף את רשת הידע. כך נוכל לקבץ את המידע לפי נושאים שונים ולמצוא קישורים בין נושאים שונים בעלי קשר הדוק. התובנות שיתקבלו בעזרת שתי השיטות האלה ישמשו לחלוקה של התיעוד הכולל דף יחיד למספר דפים. לאחר מכן אפשר לקשר את החבילה כולה ולהצליב אותה ב-Markdown. כתוצאה מכך, תהיה גרסה מאורגנת יותר של מסמכי ההגדרה, שקל יותר לנווט בה ולהבין אותה.
מוטיבציה למרות העובדה שאני משתמש בתוכנת קוד פתוח כבר לא מעט זמן, ההיכרות שלי עם המונח היא די חדשה, בדומה לידע שלי בתוכנת Linux. כשהתחלתי ללמוד Python (דרך edX), תהיתי איך שגיאות קטנות יכולות להרוס את הקוד. חשבתי שיהיה נחמד לבדוק את הקודים שלך, איכשהו, ולזהות את השגיאות שלך, ואז למדתי על המונח "linting". עדיין לא השתמשתי בתוכנת linting בצורה נכונה, אבל אני בטוח שזה יקל על החיים שלי בעתיד.
עם רקע בהנדסת חשמל ועם ניסיון מסוים בתכנות, אני יכול להבין טוב יותר את הבעיות בתכנות ואת הדרישות של מתכנתים. בנוסף, התואר השני שלי בתקשורת טכנית ומקצועית מאפשר לי לתמוך במשתמשים, בניסיון להקל על אנשים. הכישורים והמומחיות שלי ישמשו כשילוב מנצח בפרויקט הזה, ויוסיף ערך לתיעוד של ESLint.
מטרות מטרת העל של הפרויקט היא לוודא שקל להבין את המסמכים בדף ההגדרות של ESLint ולא מציפים את המשתמשים. כדי שהפרויקט יצליח, חשוב שהניווט בתוכן יהיה קל וללא כל סיבוכים. המטרות החשובות של הפרויקט הן: - ביצוע ביקורת תוכן מקיפה - יצירה של ארכיטקטורת מידע כדי להבין את זרימת המידע - שיפור ארכיטקטורת המידע וארגון מחדש של התיעוד - זיהוי קישורים והפניות בין קטעים שונים של התוכן - שכתוב/עריכה של חלקי המסמך, אם יש צורך כדי לעמוד בדרישות ההגדרה מחדש
- הבטח שהתוכן גמיש וניתן לשימוש חוזר
תיאור הפרויקט ההגדרה של ESLint היא תכונה חשובה שמאפשרת להתאים אישית את ESLint. משתמשים שמעוניינים בהגדרה יהיו מעוניינים, ללא ספק, בהיבט אחד או שניים בכל רגע נתון. לכן חשוב שהמשתמש יונחה לגבי נושא העניין המסוים שלו, וכך יספק לו את הפתרון בצורה יעילה. המצב הנוכחי של תיעוד ההגדרות של ESLint מכיל הרבה מידע שימושי, אבל הוא מאורגן באופן שמאפשר למשתמשים להרגיש מוצפים, מתוסכלים ואבודים. למשל, אם מישהו רוצה ללמוד על השימוש ביישומי פלאגין של צד שלישי ב-ESLint, הוא יצטרך לגלול למטה עד לסיום הדיון בנושא הגדרת מנתח, סביבות ו-globals. כל התהליך הזה מעייף את המשתמשים ועלול להרחיק אותם מהאתר. באופן דומה, אם משתמש נמצא במקום כלשהו באמצע הדף והוא רוצה לעבור לקטע מסוים או רק כדי לעיין בנושאים דומים, זו לא תהיה משימה קלה מבחינתו, מאחר שסיוע כזה לא מסופק למשתמשים. צריך לטפל בבעיות האלה באופן מיידי, כי איכות המסמכים, לא משנה עד כמה הם מסודרים, תלויה במידת היעילות שלהם. אני מציע פתרונות לבעיות אלה ואחרות, במהלך הדיון הבא.
בדיקת תוכן השלב הראשון בתהליך הארגון מחדש של מסמכי ההגדרה הוא לבצע ביקורת תוכן מקיפה. מטרת הביקורת היא לזהות כמה בעיות מרכזיות, כמו תוכן מיושן, כפילויות, תוכן חסר וכו'. גיליון אלקטרוני של ביקורת תוכן שנוצר בעקבות זאת ישותף עם צוותי הניהול והתיעוד כדי לקבל מהם משוב. כך תוכלו לגבש אסטרטגיה חדשה למבנה ולהצגה של המסמכים.
יצירה של ארכיטקטורת מידע כדי להבין את רשת הידע או את זרימת המידע במסמכי התצורה, יצירה של ארכיטקטורת מידע (IA) יכולה להיות דבר חשוב. ממצאי בדיקת התוכן ישמשו כבסיס טוב להבנה ולפיתוח של זרימת המידע. לאחר מכן תיווצר גרסה משופרת של ה-IA כדי לארגן ולהציג את התיעוד בצורה טובה יותר. שיפור זה לא רק יבנה מחדש את התוכן הנוכחי, אלא גם יזהה קישורים ומזלגות בין קטעים שונים בתיעוד, וכך תיצור רשת יעילה. לדוגמה, אחרי התוכן שמופיע בדף 'הגדרת כללים' יכול להופיע קישור שמוביל ל'השבתת כללים עם תגובות בתוך השורה'. ניתן לזהות גם קישורים אחרים כאלה וכך ליצור קשרים בין קטעים שונים במסמך.
כדי ליצור תוכן עניינים מפורט עם קישורים שמובילים לסעיפים ולקטעי משנה ספציפיים במסמך, הביקורת של תוכן העניינים ו-IA יסופקו. יצירת קבצים נפרדים לכל קטע והוספת הפניות מתאימות לסעיפים אחרים יכולים להוסיף ערך לכל קבוצת המסמכים. אפשר ליצור תוכן עניינים למשתמשים שמגיעים למסמכי התיעוד, וכך לסייע להם במהלך הגלישה באתר. תוכן העניינים יכול לכלול את כל הכותרות ברמה הראשונה והשנייה כדי שהוא יהיה קצר אך מקיף. אחד משיטות הפעולה האלה, למשל, הוא השימוש של Prettier (https://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: קישורים והפניות במהלך השלב הזה אנתח את ה-IA כדי למפות קישורים והפניות בין סעיפים שונים בתיעוד. גם אצור היררכיה של כל הקטעים, וכך אשפר את ה-IA תוך כדי התהליך.
1 באוקטובר 2020 עד 3 באוקטובר 2020: המפה הסופית בעזרת התובנות שהפקתם מביקורת תוכן ומ-IA, אצור מפה סופית שתוטמע בתיעוד המאורגן מחדש של ההגדרות. המפה המקיפה הזו תכיל תוכן עניינים, היררכיית נושאים ורשימה של קישורים והפניות בין קטעים שונים של התיעוד.
4 באוקטובר 2020 עד 5 באוקטובר 2020: דיון במועד הזה, לפני עריכת המסמכים, אציג את הממצאים ואת תוכניתי למנטורים ולצוותים הרלוונטיים. המשוב שלהם יעזור לשפר את התוכנית ולבצע שינויים במידת הצורך.
6 באוקטובר 2020 עד 20 באוקטובר 2020: שכתוב ועריכה בתקופה הזו אערוך ואעדכן את הקטעים במסמכים שבהם נדרשת עבודה. יכול להיות שחלקים מסוימים במסמכי התיעוד בנושא ישוכתבו, או שיתווספו נתונים חדשים. בשלב הזה נתמקד בהבטחת הדיוק, בעדכון, בגמישות ובניתן לשימוש חוזר.
21 באוקטובר 2020 עד 25 באוקטובר 2020: תיקונים וקישורים בשלב הזה אבדוק את העבודה שלי כדי לתקן שגיאות דקדוק ומבניות, וגם לבדוק שוב את רמת הדיוק של העבודה שלי. אני אוסיף גם קישורים והפניות בין סעיפים, בהתאם ל-IA, כדי להבטיח שהתיעוד תואם למפת הידע שניתנה קודם לכן.
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: דוח פרויקט דוח מפורט של הפרויקט ייווצר בתקופה הזו של 5 ימים. היעדים, המאבקים, הבעיות והפתרונות המוצגים יהיו חלק מדוח הפרויקט. הדוח ישותף עם המנטורים כדי לקבל את המשוב.
29 בנובמבר 2020 עד 30 בנובמבר 2020: הגשה סופית הפרויקט, עם כל הקבצים ודוח הפרויקט יוגש למנטורים. בחינה של הפרויקט כולו תתקיים באמצעות פגישה או דיון עם המנטורים והצוותים הרלוונטיים.
במהלך הפרויקט, אמשיך להתייעץ עם המנטורים כדי לקבל מהם משוב חשוב. ניתן לשנות את כל אבני הדרך האלה בהתאם לדיונים עם מנטורים בקשר למפגשים עם הקהילה ולתקופות של בדיקת הצעות.
מי אני יש לי תואר ראשון בהנדסת חשמל ותואר שני בתקשורת טכנית ומקצועית מאוניברסיטת מדינת צפון קרוליינה. יש לי ניסיון בתחומים טכניים ומקצועיים של כתיבה ועריכה, תקשורת וניהול תוכן, לימודי נוחות השימוש באינטרנט ובנייד ובעיצוב הוראה. עבדתי כעורך משנה של אתר חדשות באינטרנט (Global Village Space) וכמתמחה בתקשורת עבור דיוק פורג' באוניברסיטת דיוק. במקביל, יש לי גם עניין בכתיבה יוצרת.