דף זה מכיל את הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- קוליברי
- כתב טכני:
- StephDix
- שם הפרויקט:
- מוסכמות בסגנון התיעוד של המערכת האקולוגית ב-Kolibri ותהליכי עבודה
- אורך הפרויקט:
- תקופה ארוכה (5 חודשים)
תיאור הפרויקט
מופשט
המסמך הזה מפרט איך ליישם את הנחיות הסגנון ואת ניהול תהליכי העבודה במידע המתועד של Learning Equality עבור פרויקט המערכת האקולוגית של Kolibri.
סקירה כללית
ההצעה שלי מורכבת מארבעה שלבים. בשלב הראשון, אציג את מדריך הסגנון של מסמכי LE בנושא נגישות עם הנחיות בנושא נגישות, כתיבה ופורמט בהתאם לקונספטים ולהנחיות הסגנון של LE בפיתוח תוכנה. בשלב השני, אבצע ביקורת איכות על מסמכי ReadTheDocs ו-GoogleDocs. תוכנית הביקורת משלבת את השימוש ברשימות של משימות כדי להעריך את התאימות להנחיות הסגנון. רשימות המשימות האלה יעזרו לתעד את הממצאים ולהחיל שינויים במסמכים. בשלב השלישי אעבוד על המבנה, המראה והתחושה של תבניות מתוך מסמכי ReadTheDocs ו-GoogleDocs. אצור מאגר תבניות ותמונות ב-Google Drive לזיהוי כל קטגוריית תבניות של סוגי מסמכים עיקריים לשימוש חוזר בהטמעות הבאות. אני אמלא את המשימה הזו של יצירת תבניות כדי לאפשר זיהוי קל של בעיות במסמכים בתהליך הבדיקה של בקשות משיכה. לבסוף, אצור מדריך לתורמי תוכן שמקבץ מקורות מידע שימושיים לכל קבוצת שותפי עריכה כדי לשפר את חוויית הגישה שלהם למידע.
מטרה והיקף
מטרת תוכנית ההטמעה היא לשפר את החוויה של משתמשי הקצה שמשתמשים במסמכים של Kolibri ולעזור לחברי הצוות ולתורמים להפיק תיעוד טוב יותר ושיתוף פעולה פעיל בקהילה. היישום הזה חל על ReadTheDocs ועל קבוצות משנה של מסמכי Google Docs במערכת האקולוגית של Kolibri.
קהל
קהל עיקרי של מיישמים, אדמינים ומשתמשי קצה הוא הצרכנים החשובים ביותר של התיעוד של Kolibri. קהל משני של חברי צוות ושותפי עריכה להפקת התיעוד של Kolibri והשימוש בהם.
מטרות
מדריך סגנון ומערכת תהליכי עבודה עבור התיעוד של המערכת האקולוגית של Kolibri מצפה מהמשתמשים: ליצור תיעוד קל לעיכול, בשפה נגישה ובפריסה עקבית. לשמור על תחזוקה של נוהלי האיכות במסמכים. לאפשר גישה נוחה למידע בין ערוצי התיעוד. לחזק את היוזמות השיתופיות בקהילת הקוד הפתוח של Kolibri.
מקורות מידע
מקורות המידע שלי היו Kolibri, Kolibri Studio, מסמכי פיתוח RTD של Kolibri Development וערכת כלים של Kolibri מ-Google Drive.
חברת Radina Matic הנפלאה עזרה מאוד בביצוע פעילויות חימום ופעילויות ספציפיות לפרויקט. המשוב שלה לגבי מה שהארגון הגדיר כ"הנחיות" ו"מדריכים", ולגבי קיומו של מדריך לתורמים, עזר לי לארגן את הרעיונות ולכתוב מסקנות.
תוכנות
אפתח את טיוטה של מדריך הסגנון ב-Google Docs. פלטפורמת המסמכים הזו מושלמת כדי לחזור עליה בזמן שהיא מוכנה לפרסום. לבקרת QA, אני רוצה להשתמש ב-Google Forms כדי לנהל מסמכים ולהעריך אותם. התשובות לטופס יישמרו בגיליון אלקטרוני לצורך בקרת מסמכים. ארגון מחדש של מסמכי RTD באמצעות GitHub. עבדתי עם Git, Gitkraken, GitHub ו-Gitlab. יש לי ידע מעשי ב-Markdown וגם בכמה RestructuredText. אני מתכוון לתרום לתיקוני התיעוד כדי להמשיך ללמוד את התחביר. אני אשתמש ב-Sharex לתמונות ולקובצי GIF. אני אוהב את הכלי הזה כי הוא מעבד בפורמטים שונים של פלט. אני אשתמש בתרשימים לדיאגרמות ולמהדורת תמונות. תוכנת התרשימים משתלבת מצוין עם Google Docs, Google Drive ו-LibreOffice. מצב התיעוד בשלב החקירה, תיקנתי את רוב המסמכים של Kolibri. מצאתי שגיאות דקדוק, שגיאות הקלדה, חוסר עקביות בפריסה, בטיפוגרפיה, בשימוש בתמונה וגם בנתיבי תיעוד מבלבלים ברוב מסמכי הפרויקט. לדוגמה, במדריך למשתמש של Kolibri הקטע לפתרון בעיות מתייחס לנושא משנה ולא לנושא. המידע הזה הוא קריטי מספיק כדי שמשתמשי הקצה יוכלו לגשת אליו מתוכן העניינים. כחלופה נוספת, הם יכולים להשתמש בסרגל החיפוש ובעץ תוכן העניינים כדי להרחיב נושאים אחרים ולאתר מאמרים לפתרון בעיות.
כדי להיכנס לקטע 'פתרון בעיות', עליכם לחפש את הבעיה או להרחיב את הקטע 'ניהול קוליברי' כדי להבין שקיים פתרון בעיות כחלק מהתיעוד. מדריך לעומת הנחיות להצעה לפרויקט הזה, ניתחתי שני מסמכים: מדריך הסגנון לתיעוד משתמש של LE Kolibri והנחיות לתרגום LE. במדריך של LE Kolibri, נתתי המלצות ותגובות מתוך מתאר הנושא ותוכנית התיעוד שהצעתי, וכן כמה דברים נוספים שדורשים שיפור במדריך. בהנחיות התרגום של LE, שיניתי את הפורמט והסגנון בהתאם להמלצות שלי ומוסכמות קיימות במדריך הסגנון. הדבר שהכי גילה לי במהלך הניתוח היה תפיסה שגויה שקיימת בין מסמכים שמסווגים כ'מדריך' ו'הנחיות'.
תוצאות
ביצעתי בדיקת איכות למדריך התרגום של LE בנוסף להצעות ולתגובות באמצעות טופס מקדים שעליו הסברתי בפירוט במשימת הביקורת לבקרת איכות. הנה כמה הערות סופיות שהתקבלו מההערכה: קישורים מנותקים עבור אתר ICU Syntax .js הפורמט ששימש ליצירת הנחיות אלה שגוי. המסמך הוא מדריך ולא הנחיות. חוסר עקביות בטיפוגרפיה. שימוש שגוי בכותרות ובכותרות, שימוש לא הולם בשפה ושימוש לרעה בקיצורים. שימוש בלתי הולם בטקסטים חלופיים. יותר מדי הצהרות/ הוראות שחוזרות על עצמן.
הממצאים של שני המסמכים הם חלק מפרטים בהצעה הזו.
משימות ספציפיות לפרויקט
- המלצות למדריך הסגנון לתיעוד משתמש של LE (תגובות)
- הנחיות התרגום של LE עם סגנונות ופורמטים חדשים.
- מתאר הנושאים
- ציר הזמן של הפרויקט
- משימות תיעוד