בדף הזה מפורטים פרטי פרויקט של כתיבה טכנית שאושר להשתתפות בתוכנית Google Season of Docs.
סיכום הפרויקט
- ארגון בקוד פתוח:
- CERN-HSF
- כותבים טכניים:
- LuckInTheRain
- שם הפרויקט:
- מסמכי תיעוד של ROOT: ניתוח, שינוי מבנה וכתיבה מחדש
- אורך הפרויקט:
- Long running (5 months)
תיאור הפרויקט
הפרויקט מורכב מארבעה שלבים:
1.) ניתוח של מסמכי התיעוד הנוכחיים של ROOT
מסמך ה-ROOT המלא (אתר אינטרנט, מדריך למשתמש, חומר עזר בנושא C++, מדריכים וכו') מנותח ונבדק לפי הקריטריונים הבאים: מבנה, מודולריות, סטנדרטיזציה, מנגנוני גישה, עקביות, סוגי המידע שבהם נעשה שימוש, הכנה ספציפית לקבוצת היעד וקלות הבנה. המטרה היא ליצור קונספט לניהול מידע, מטריקס ליצירת מבנה והנחיה ליצירת סטנדרטים לתוכן.
2.) הגדרת שיטת מבנה למסמכי עזרה של תוכנות כתיבה עם צוות ROOT
הצגת DITA (Darwin Information Typing Architecture) – תקן OASIS לתיעוד תוכנה (https://www.oasis-open.org/committees/dita/) לצוות ROOT. המיקוד העיקרי הוא הבנת האופן שבו ניתן לבנות תוכן ספציפי לתוכנה, ואיך סוגים של מידע בסיסי כ"קונספט", "משימה" ו"הפניה" משמשים לכתיבת מסמכי תוכנה.
3.) שינוי המבנה והארגון של מסמכי העזרה של ROOT
על סמך התוצאות של שני השלבים הראשונים, מתבצעת חלוקה מחדש של מסמכי התיעוד של ROOT למודולים לפי קבוצות יעד, תפקידים ותרחישי לדוגמה, והתוכן מוקצה לרכיבים ולסוגי התוכן המתאימים (אתר אינטרנט, מדריך למשתמש, מסמך עזר בנושא C++, מדריכים וכו'). מאחר שהמידע הזמין הוא נרחב מאוד, יש גם ליצור מבנה עזר עקבי. המטרה היא לספק סקירה כללית מקיפה ולהראות למשתמשים דרכים ברורות שבהן הם יכולים להשתמש ב-ROOT בהתאם לצרכים שלהם. בנוסף, מוצגת מבוא קומפקטי שלא מתמקד בפיזיקה.
4.) כתיבת מחדש של מסמכי התיעוד של ROOT
החלקים העיקריים במסמך, במיוחד המדריך למשתמשים, משוכתבים בהתאם לגישת DITA. כללי המבנה והכתיבה מתועדים במדריך סגנון כדי להבטיח עקביות במסמכים בעתיד. המטרה היא לאפשר לצוות ROOT להרחיב ולתחזק את המסמכים של ROOT בעצמם בעתיד.
לוח הזמנים המשוער (5 חודשים):
שלב 1: ניתוח התיעוד הנוכחי לגבי ROOT: 3 שבועות.
שלב 2: הגדרת שיטה למבנה של תיעוד כתיבה של תוכנה עם צוות ROOT: שבועיים.
שלב 3: שינוי המבנה והארגון של מסמכי התיעוד של ROOT: 4 שבועות.
שלב 4: כתיבת מחדש של מסמכי התיעוד של ROOT: 11 שבועות.