בדף הזה מופיעים הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Docs ל-Google Docs.
סיכום הפרויקט
- ארגון בקוד פתוח:
- CERN-HSF
- כותבים טכניים:
- Ariadne
- שם הפרויקט:
- Rucio – Modernize (restructure & rewrite) the Rucio documentation
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
תקציר: התשתית של Rucio פותחה כדי לנהל ולארגן כמויות גדולות של נתונים מדעיים שמפוזרים גיאוגרפית במרכזי נתונים הטרוגניים. ה-framework מציע יכולות כמו שחזור נתונים מבוזר ורפליקציה אדפטיבית, עם יכולת התאמה רחבה, מודולרית והרחבה. צרכני התיעוד של שירות כזה יכולים להגיע מרקעים שונים ויש להם דרישות שונות כשהם ניגשים לשירות. לכן, תיעוד טוב של שירות כזה אמור לפשט את השימוש בו על ידי משתמשי הקצה, וגם לשמש כמקור מידע לבעיות נפוצות ולפתרון בעיות.
ללא תיעוד כזה, יהיו מכשולים משמעותיים בשימוש יעיל ואפקטיבי. מצב כזה עלול להוביל לעלייה בעלויות התמיכה ולסיכון למוניטין של המותג של המוצר. תיעוד הוא, בסופו של דבר, אמצעי תקשורת. לכן, חשוב לוודא שהתקשורת מוטמעת במסגרת שניתן לנהל ולגשת אליה, תוך שמירה על רלוונטיות באמצעות ניהול גרסאות מתאים.
בזמן כתיבת המאמר הזה, המערכת של Rucio שימשה לצורך דרישות האנרגיה הגבוהה של ניסויי ATLAS ו-CMS ב-LHC. הוא משמש גם לתמיכה בצרכים של קהילות מדעיות מגוונות מעבר ל-LHC, כמו אסטרופיזיקה. לכן, חשוב שהמסמכים יהיו רלוונטיים ונגישים ככל האפשר. בעזרת הפרויקט הזה, CERN רוצה לספק למשתמשים הקצה של Rucio תצוגה מרוכזת של כל המסמכים הרלוונטיים, כדי לאפשר להם ליהנות מחוויית שימוש חלקה בזמן השימוש במסגרת.
המצב הנוכחי: נכון להיום, מסמכי התיעוד למשתמשים מפוזרים במקומות שונים ובפורמטים שונים, כולל מאמרים מדעיים, readthedocs.io עם המקור בקוד, Google Drive, GitHub, DockerHub או ויקיס. שימוש במספר מקורות גורם לבעיות במעקב אחר הגרסאות ובתקינות של מסמכי התיעוד. בנוסף, מודל תיעוד מבוזרת יוצר מכשולים משמעותיים בניווט ובחשיפת מידע רלוונטי לתרחיש לדוגמה. במיוחד במקרה של ויקיס, יכול להיות שהמידע שסופק לגבי ניסוי מסוים רלוונטי גם למופעים אחרים שנמצאים באותם מקורות או במקורות אחרים. עם זאת, בגלל חוסר קונסולידציה וקישורים מתאימים, המידע הזה לא מנוצל במלואו.
למה המסמך המוצג שלך הוא שיפור על פני המסמך הנוכחי? לאור הבעיה הרבגונית, המודל המוצע למטה מבטל את הבעיות בניווט, ניהול גרסאות, מעקב וחשיפת מסמכים כמפורט למטה:
המטרה של שינוי המבנה של המסמכים היא לפשט את התהליך של הניווט למשתמש הקצה. הוא או היא לא יצטרכו להיכנס למבוך בזמן החיפוש של מידע, כי המידע יסווג או יסומן לצורך פשטות. מבחינה מנהלית, ניהול הגרסאות והמעקב יהיו קלים יותר, כי המבנה המחודש יאפשר לכם לסווג את הפריטים על סמך הצרכים שלכם. ריכוז כל התיעוד של המבנה מחדש נועד להבטיח שכל המידע גלוי למשתמש מבלי להפנות למספר מקורות.
ניתוח: לאחר קריאת תקציר הדרישות ושיחות עם צוות ההדרכה, אלה המסקנות שלי לגבי המצב הנוכחי של מסמכי העזרה של Rucio:
יש שישה מקורות מרכזיים למסמכי עזר: - קישור ל-Google Drive : https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7
Readthedocs שמופעל על ידי Sphinx עם מקור בקוד קישור לקוד: https://github.com/rucio/rucio קישור ל-ReadtheDocs: https://rucio.readthedocs.io/en/latest/
DockerHub קישור: https://hub.docker.com/u/rucio
קישור ל-GitHub: https://github.com/rucio/rucio
Wikis קישור: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing
מאמרים מדעיים קישור: https://arxiv.org/AB/1902.09857
המסמכים במקורות האלה מופיעים בפורמטים שונים. לדוגמה: ל-Google Drive יש מסמכים בצורה של Slides ו-Docs, ב-GitHub יש קבצים בעיקר בשפת הסימון reStructuredText וכו'. אין מספיק ניהול גרסאות ומעקב, וכתוצאה מכך מידע מיותר מתפרסם בכמה מקורות. אין אחידות בתיוג או בסיווג של מידע. לכן, נדרש ניסיון קודם ומומחיות במהלך החיפוש.
בהתחשב במגוון הפורמטים והמקורות, הציפייה היא לארגן מחדש את המידע ולרכז אותו באמצעות mkdocs. כדי לשפר את הבנתי על הכלים, חקרתי והכרתי את השימוש בהם.
קביעה: המסמכים הקיימים לא מובנים ומפוזרים ללא קישור מתאים. בנוסף, אין בה ריכוז ועקביות בפורמט. כתוצאה מכך, המשתמשים צריכים להשקיע מאמצים נוספים בחיפושים. פערים כאלה גם יוצרים לחץ מיותר על האדמינים, על המנהלים או על מנהלי הפרויקטים, ולכן קשה יותר לשמור על גישה שמבוססת על קהילה לתחזוקה ולעדכון של המסמכים. חוויית המשתמשים והשותפים ביצירת התוכן נפגמת באופן משמעותי, ולכן
המבנה של המסמכים המוצעים:
לאחר ניתוח מעמיק של הדרישות, החלטתי לטפל בבעיות העיקריות באמצעות מודל תיעוד מחדש.
המודל המבנה מחדש מוצג בתוכנית האב שמצורפת בהמשך, וכל פריט תיעוד יסווג לפי 7 הקטגוריות הבאות:
- מידע כללי
- תחילת העבודה
- מושגים
- ממשקים רוסיו
- Tasks
- מדריכים
- ידע מתקדם
כמובן, יש שיפורים שאפשר לבצע, כמו הוספת קישורים, ואני רוצה לעבוד עליהם אחרי סיום התוכנית. יש יותר מ-1,000 משתמשים פעילים שגולשים ב-500 פטה-בייט של נתונים ב-Rucio, והארגון מציע לבצע שינוי מבני במסמכי העזרה כדי לצמצם באופן משמעותי את הצורך של המשתמשים לפנות לרשימת התמיכה. היעד יהיה לשפר את חוויית המשתמש על ידי הפחתת מספר שיעורי הקליקים ופרסום קל של מסמכי התיעוד באמצעות סיווג ותיוג. כל מה שצריך לדעת מנקודת המבט של משתמשים, צוות תפעול או צוות אדמין יהיה זמין תוך 3 קליקים או פחות.
קישור לגרסת מודל: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)
יעדי הפרויקט: - ניתוח וחיסכון במידע מיותר שזמין ממקורות שונים. כלומר, לכל פריט מידע צריך להיות מקור מידע אחד. - שינוי המבנה על ידי תיוג וסיווג של המסמכים הקיימים לחלקים שונים - העברת המסמכים ששונו למבנה המרכזי על סמך mkdocs - שינוי הפורמט או ייבוא של מסמכים שלא ניתן להעביר בגלל אילוצים של פורמט הקובץ - הגדרת שינוי של המסמכים על ידי הקהילה כדי לוודא שכל הפערים ימולאו – מבחינת קישורים, עדכוני מידע או תיקון שגיאות.
היסודות של המערכת הזו כבר קיימים, אבל המודל שלי ישפר את המערכת הקיימת על ידי הגדרת הנחיות מתאימות לתרומה ולניהול עם תיעוד מתאים. בנוסף, אני רוצה לשלב לוחות פרויקט של GitHub כדי לעקוב אחר בעיות ולבדוק את התקינות הכוללת של הפרויקט.
ציר זמן: - לפני 16 באוגוסט --> להכיר את הגרסאות הנוכחיות של המסמכים הטכניים ושל Rucio --> ללמוד טכניקות חדשות וכישורי כתיבה טכנית שיעזרו במהלך הפרויקט --> לתרום לפתרון בעיות במסמכים הטכניים, אם יש כאלה, שדווחו ב-GitHub
יצירת קשרים בקהילה (17 באוגוסט עד 13 בספטמבר) --> הגדרת ערוץ תקשורת ושעה שתואמים להבדל בין אזורי הזמן (השעה בפונה היא 3 שעות ו-30 דקות לפני השעה בארץ) --> זיהוי נקודות כאב עיקריות לצורך שינוי היעדים בהתאם --> התעניינות בשיחות כדי לקבל מידע נוסף על הקהילה, הארגון והמסגרת. --> הערכה של מבנה התיעוד המוצע עם מנחים ועם חברים חשובים אחרים בארגון, כדי לבדוק את הכדאיות וההיתכנות של ההטמעה. --> סיום של התכונות המוצעות וכל שינוי אחר שעשוי להיות צורך לבצע במסמכים הקיימים.
תקופת התיעוד (14 בספטמבר עד 30 בנובמבר) בהתאם לפורמט שהצעתי כאן, סיפקתי פירוט של אבני הדרך העיקריות שאני מתכנן להשיג במהלך תקופת התיעוד.
--> ציון דרך מס' 1: סיווג ותיוג ETC: 28 בספטמבר 2020 הטמעת המסמכים הזמינים ותיוג שלהם פשוטות מאוד את תהליך השינוי והצמצום.
--> ציון דרך מס' 2: ניתוח, גיזום ושינוי מבנה תאריך היעד: 19 באוקטובר 2020 התיעוד שסווג במהלך ציון הדרך מס' 1 ייבדק כדי למצוא כפילויות ומקורות מידע מיותרים. כפי שצוין בפרטים של הפרויקט, אנחנו שואפים ליצור מקור מידע אמין אחד לכל המידע שזמין.
--> ציון דרך מס' 3: ריכוז ועיצוב מחדש: ETC: 9 בנובמבר 2020 אחרי שנסיר את החלק הלא רלוונטי ונבנה מחדש את המסמכים בצורה נכונה, אנסה לעצב אותם מחדש. בגלל המקור השונה, הפורמטים שונים וצריך קודם להמיר אותם לפורמט מתאים. לאחר מכן, תהליך הריכוז יהיה קל יותר.
--> יעד מס' 4: הגדרת לוחות מעקב + מסמכים בנושא פיקוח/תרומות ETC: 23 בנובמבר 2020 השלב הזה נועד לוודא לאחר השלמת הפרויקט, התיעוד ימשיך להיות עדכני. הגדרת הנחיות והקמת לוחות פרויקטים יעזרו לחברי הצוות הניהולי לגייס תרומות מהקהילה ולעקוב אחריהן בצורה יעילה.
--> הערכת הפרויקט (30 בנובמבר עד 5 בדצמבר) שליחת דוח על הפרויקט והערכה של המנטורים שלי כתיבה ושליחה של דוח על החוויה שלי כמשתתף ב-Season of Docs.
למה דווקא הפרויקט הזה? האמנתי ששילוב של קוד עם תיעוד שנכתב היטב ומחולק לגרסאות הוא הדרך היחידה לעודד את השימוש ב-API ולשפר אותו. באופן אישי, התרשמתי מאוד מהאופן שבו CERN חלוץ במחקרים מתקדמים בתחומים שונים של הפיזיקה. בהתחשב בהיקף המידע שעובד, מועבר ונוצר במהלך ניסויים כאלה, תמיד עניין אותי איך מנהלים את הנתונים לצורך עיון ושימוש עתידי בתוך הארגון. אשמח לתרום לשיפור המסמכים של מסגרת שסייעה במחקרים מדעיים מדהימים ובגילויים מדהימים.
למה אני האדם המתאים לפרויקט הזה? בנוסף לעמידה בדרישות המוקדמות, אני בטוח/ה שאני האדם המתאים לפרויקט הזה כי:
כבר התחלתי לשנות את המסמכים הקיימים של Kubernetes. בעקבות התרומות האלה, הצטרפתי לצוות של 'עותק צל של מסמכי הגרסה' במחזור הגרסאות 1.19 של Kubernetes, שבו אני תורם לתחזוקה ולשדרוג של מסמכי העזרה של התכונות החדשות שנוספות במהלך הגרסאות. לדעתי, תיעוד טוב הוא עמוד השדרה של מוצר או שירות מעולים. בין אם מדובר במידע פרוצדורלי או טכני, מידע מנוסח היטב, תמציתי ונגיש בקלות יוכל לעודד את האימוץ ולעזור לשימוש טוב יותר. לאורך הקריירה שלי עבדתי עם מערכות מבוזרות מבוססות-נתונים, ולכן אני חושב שיש לי את היכולת הטובה ביותר להבין את המורכבות של הדרישות לגבי תיעוד של מערכות כאלה. כמשתמש קצה בעצמי, אני מכיר את המלכודות של תיעוד שגוי או כתוב בצורה גרועה, ואקפיד להביא אותן בחשבון במהלך המבנה מחדש.