דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- CERN-HSF
- כתב טכני:
- אריאדנה
- שם הפרויקט:
- Rucio – מודרניזציה (בנייה מחדש ושכתוב) של המסמכים של Rucio
- אורך הפרויקט:
- אורך רגיל (3 חודשים)
תיאור הפרויקט
מופשט: מסגרת Rucio פותחה במטרה לנהל ולארגן כמויות גדולות של נתונים מדעיים המופצים גיאוגרפית על פני מרכזי נתונים הטרוגניים. ה-framework מציע יכולות כמו שחזור נתונים מבוזר ושכפול גמיש, ולכן ה-framework ניתן להתאמה, מודולרי וגמיש מאוד. צרכני המסמכים לשירות כזה צריכים להגיע מרקעים שונים, ויש להם דרישות מגוונות כשהם ניגשים לשירות. תיעוד טוב של שירות כזה צריך, בין השאר, לפשט את השימוש בו ולהיעזר בו למשתמשי הקצה, ומהווה גם הפניה לבעיות נפוצות ולפתרון בעיות.
אם לא נקבל תיעוד כזה, יהיו קשיים משמעותיים בשימוש יעיל ואפקטיבי. דבר כזה עלול להוביל לעלייה בעלויות התמיכה ולסכן את המוניטין של החברה לזהות של המוצר. תיעוד הוא, אחרי הכל, אמצעי תקשורת. כדי להבטיח שהתקשורת תהיה מנוסחת כך שתהיה נגישה וניתנת לניהול, ובמקביל להמשיך להיות רלוונטית עם ניהול גרסאות מתאים, אנחנו נקיים את התקשורת בינינו.
נכון לכתיבה זו, נעשה שימוש במסגרת של Rucio כדי לעמוד בדרישות אנרגיה גבוהה של ניסויי ATLAS ו-CMS ב-LHC. הוא גם משמש לתמיכה בצרכים של קהילות מדעיות מגוונות מעבר ל-LHC, כמו אסטרופיזיקה; וכך הופך את התיעוד לרלוונטי ונגיש ככל האפשר. בעזרת הפרויקט הזה, CERN רוצה לאפשר למשתמשי הקצה של Rucio ליהנות מחוויית שימוש חלקה תוך שימוש ב-framework של תמונה מרוכזת שתאפשר גישה לכל המסמכים הרלוונטיים.
המצב הנוכחי: נכון להיום, מסמכי התיעוד על המשתמשים מתפרסים בכמה פורמטים שונים, כולל מאמרים מדעיים, readthedocs.io עם מקור בקוד, Google Drive, GitHub, DockerHub או Wikis. קיימים מקורות שונים שגורמים לבעיות במעקב אחר גרסאות ונכונות התיעוד. נוסף על כך, מודל תיעוד מבוזר מהווה מכשולים משמעותיים בניווט ובחשיפת מידע רלוונטי למקרה שימוש נתון. במיוחד במקרה של Wiki, המידע המסופק לניסוי מסוים עשוי להתאים גם למקרים אחרים הממוקמים באותם מקורות/אחרים. עם זאת, עקב היעדר איחוד וקשרים מתאימים, מידע זה נשאר רדום, ולפעמים גם לא מנוצל במלואו.
למה התיעוד המוצע למשתמש הוא שיפור בהשוואה למסמך הנוכחי? בהתחשב בבעיה רבת ההיבטים, המודל המוצע למטה מבטל את המכשולים עם ניווט, ניהול גרסאות, מעקב והצגה של מסמכים כמפורט למטה:
שינוי המבנה של המסמכים נועד לפשט את המאמצים המושקעים בניווט עבור משתמש קצה. הוא/היא לא צריכים להיכנס לחורי ארנב כשהם מחפשים מידע מכיוון שהם יסווגו/יסומנו בתווית לשם פשטות. מנקודת מבט מנהלית, ניהול גרסאות ומעקב יהיה קל יותר מכיוון ששינוי המבנה יאפשר חופש לסווג על בסיס דרישה. כדי להבטיח שכל המידע יהיה גלוי למשתמשים בלי להפנות לכמה מקורות, כדאי לרכז את כל התיעוד המובנה מחדש.
ניתוח: לאחר קריאת תקציר הדרישות וניהול שיחות עם צוות החונכות, הניכויים שלי מהמצב הנוכחי של מסמכי התיעוד של Rucio הם:
קיימים שישה מקורות תיעוד עיקריים: - קישור ל-Google Drive : https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7
Readthedocs מופעל על ידי Sphinx עם המקור בקוד Link to Code: https://github.com/rucio/rucio קישור ל-ReadtheDocs: https://rucio.readthedocs.io/en/minute/
DockerHub קישור: https://hub.docker.com/u/rucio
GitHub קישור: https://github.com/rucio/rucio
Wikis קישור: https://twiki.crn.ch/twiki/bin/view/AtlasComputing/AtlasdistributiondComputing
קישור במאמרים מדעיים: https://arxiv.org/AB/1902.09857
המסמכים בכל המקורות האלה הם בפורמטים שונים. למשל, ב-Google Drive יש תיעוד של Slides ו-Docs, ב-GitHub יש קבצים שרובם כתובים בשפת הסימון reStructuredText וכו'. יש מחסור בגרסאות ובמעקב שמובילות לפרסום של מידע מיותר בכמה מקורות. אין אחידות בתוויות או בסיווג של המידע. לכן, נדרש ניסיון קודם ומומחיות במהלך החיפוש.
בשל מגוון הפורמטים והמקורות, הציפייה היא לארגן מחדש את המידע ולרכז אותו באמצעות mkdocs. כדי לשפר את ההבנה שלי לגבי הכלים, חקרתי ולמדתי על השימוש בהם.
תוצאה: המסמכים הקיימים לא מובנים ומפוזרים ללא קישור מתאים. הוא גם חסר ריכוז ואחיד בפורמט של הקובץ. התוצאה היא שהמשתמשים נדרשים להשקיע מאמצים נוספים בחיפוש. פערים כאלה יוצרים גם לחץ מיותר על האדמינים/האדמינים/המובילים, וכתוצאה מכך קשה לשמור על גישה מבוססת-קהילה בנוגע לתחזוקה ולעדכון התיעוד. קיימת ירידה משמעותית בחוויה של המשתמשים ושל השותפים ביצירת התוכן, לכן היו מקרים חוזרים
מבנה למסמכים המוצעים:
לאחר ניתוח מעמיק של הדרישות, החלטתי לטפל בבעיות העיקריות באמצעות מודל תיעוד מחדש.
המודל המובנה מחדש מוצג בדוגמה שמצורפת בהמשך, והוא יסווג כל חלק מהתיעוד לפי 7 הקטגוריות הבאות:
- מידע כללי
- תחילת העבודה
- מושגים
- ממשקים רוסיו
- משימות
- הדרכות
- ידע מתקדם
כמובן שיש שיפורים כמו הוספת קישורים שאני אעבוד עליהם אחרי שהתוכנית תסתיים. עם יותר מ-1,000 משתמשים פעילים הניגשים ל-500 פטה-בייט של נתונים ב-Rusio, השינוי המוצע של המסמכים יאפשר צמצום משמעותי של הצורך של משתמשים להיעזר ברשימת הדיוור של התמיכה. המטרה שלנו היא לשפר את חוויית המשתמש על ידי הקטנת מספר הקליקים והצגה קלה של תיעודים באמצעות סיווג ותיוג. כל מה שצריך לדעת מנקודת מבט של משתמש/תפעול/מנהל מערכת יהיה זמין תוך 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: אנליזה, גיזום ובנייה מחדש ETC: 19 באוקטובר 2020 מסמכים שסווגו במהלך אבן הדרך 1 ינותחו כדי לאתר כפילויות ומקורות מידע מיותרים. כפי שצוין בפרטי הפרויקט, אנחנו מטרגטים מקור אמת אחד לכל המידע הזמין.
--> אבן דרך מס' 3: ריכוז ופרמוט: ETC: 9 בנובמבר 2020 ברגע שהמסמכים יקוצרו וארגנו מחדש כראוי, אנסה קודם לשנות את הפורמט שלהם. בשל מגוון המקורות השונים, יש לשנות תחילה את הפורמטים לפורמט מתאים. לאחר מכן, תהליך הריכוז יהיה קל יותר.
--> אבן דרך מס' 4: הגדרת לוחות מעקב + תיעוד לגבי ממשל/תרומות ETC: 23 בנובמבר 2020 השלב הזה מיועד להבטיח לאחר השלמת הפרויקט, ולוודא שמסמכי התיעוד נשארים מעודכנים. קביעת הנחיות והקמת מועצות לפרויקטים יקלו על החברים המנהלתיים לבקש תרומות מהקהילה ולעקוב אחריהן ביעילות.
--> הערכת פרויקט (30 בנובמבר עד 5 בדצמבר) שליחת דוח פרויקט והערכה של המנטורים שלי כתיבה ושליחה של דוח על החוויה שלי כמשתתף בעונה של Docs.
למה דווקא הפרויקט הזה? לדעתי, הוספת תיעוד לקוד טוב והגרסה המתמשכת היא הדרך היחידה לאשר המשך אימוץ האפליקציה והשימוש בה יהיה טוב יותר. באופן אישי, הוקסמתי מהאופן שבו CERN יזם מחקר חדשני בתחומים שונים של פיזיקה. לאור היקף הנתונים שמעובדים, הועברו ומופקים במהלך הניסויים האלה, תמיד מסקרן אותי איך הנתונים מנוהלים לצורך התייחסות ולשימוש עתידי בארגון. זה יהיה לכבוד לתרום לשיפור התיעוד שלנו עבור מסגרת שמעודדת כמה מחקרים וגילויים מדעיים מדהימים.
למה אני האדם המתאים לפרויקט הזה? בנוסף לעמידה בדרישות המוקדמות, אני בטוח שאהיה האדם המתאים לפרויקט הזה כי:
אני כבר מנסה לשנות את המסמכים הקיימים ב-Kubernetes. כתוצאה מכך, הצטרפתי ל-Release Docs Shadow למחזור הגרסאות של Kubernetes בגרסה 1.19, שבו רכשתי תוכן כדי לתחזק ולשדרג ביעילות תיעוד של תכונות חדשות שמתווספות במהלך הגרסאות. לדעתי תיעוד טוב הוא עמוד השדרה של מוצר או שירות נהדר. בין אם מדובר במידע פרוצדורלי או טכני, מידע מנוסח היטב, תמציתי ונגיש בקלות יעודד שימוש טוב יותר. במהלך הקריירה שלי, עבדתי עם מערכות מבוזרות מבוססות-נתונים, לדעתי הכי טוב להבין את המורכבות של הדרישות ביחס לתיעוד של מערכות כאלה. בתור משתמש קצה בעצמי, אני מכיר את המלכודות של מסמכים שכתובים בצורה שגויה או בצורה שגויה ואקפיד לקחת אותן בחשבון במהלך השינוי.