דף זה מכיל את הפרטים של פרויקט כתיבה טכני שהתקבל בעונת Google Docs.
סיכום הפרויקט
- ארגון הקוד הפתוח:
- קוליברי
- כתב טכני:
- StephDix
- שם הפרויקט:
- מוסכמות לגבי סגנון של תיעוד המערכת האקולוגית ותהליכי עבודה
- אורך הפרויקט:
- משך זמן ארוך (5 חודשים)
תיאור הפרויקט
מופשט
במסמך הזה נפרט איך מיישמים את הנחיות הסגנון ואת ניהול תהליכי העבודה במידע המתועד של שוויון ללמידה בפרויקט של Kolibri Ecosystem.
סקירה כללית
ההצעה שלי מורכבת מארבעה שלבים. בשלב הראשון אשלים את מדריך הסגנון של מסמכי LE עם הנחיות נגישות, כתיבה והמלצות פורמט בהתאם למושגים של LE ולהנחיות הסגנון בפיתוח התוכנה. בשלב השני, אבצע ביקורת איכות על מסמכי ReadTheDocs ו-GoogleDocs. תוכנית הביקורת משלבת את השימוש ברשימות של משימות כדי להעריך את התאימות להנחיות הסגנון. רשימות המשימות יעזרו לכם לתעד את הממצאים ולהחיל שינויים במסמכים. בשלב השלישי אעבוד על המבנה, המראה והתחושה של התבניות ממסמכי ReadTheDocs ו-GoogleDocs. אני אצור מאגר של תבניות ותמונות ב-Google Drive לזיהוי כל קטגוריית תבניות של סוגי מסמכים עיקריים לשימוש חוזר בהטמעות הבאות. אני אשלים את המשימה הזו ביצירת תבניות כדי לשלוח בעיות במסמכים לזיהוי בקלות במהלך בדיקות של בקשות משיכה. לבסוף, אצור מדריך לתורמי תוכן שמרכז משאבים שימושיים לכל קבוצה של שותפי עריכה, כדי לשפר את חוויית הגישה שלהם למידע.
מטרה והיקף
הכוונה העומדת מאחורי תוכנית היישום הזו היא לשפר את החוויה של משתמשי הקצה המשתמשים במסמכים של Kolibri, ולסייע לחברי הצוות ולתורמים להפיק תיעוד טוב יותר ושיתוף פעולה פעיל בקהילה. היישום הזה חל על ReadTheDocs ועל קבוצות משנה של מסמכי Google Docs בסביבה העסקית של Kolibri.
קהל
הקהל העיקרי של מיישמים, אדמינים ומשתמשי קצה הוא הצרכנים החשובים ביותר של התיעוד של Kolibri. קהל משני של חברי צוות ושותפי עריכה לצורכי ההפקה שלהם והשימוש במסמכי התיעוד של Kolibri.
מטרות
מדריך הסגנון ומערכת תהליכי העבודה עבור התיעוד האקולוגי של Kolibri מצופים מהמשתמשים: ליצור מסמכים קריאים עם שפה נגישה ופריסה עקבית. לשמר את התחזוקה של נוהלי האיכות בזמן התיעוד. שמירה על גישה נוחה למידע בין ערוצי התיעוד. חיזוק היוזמות השיתופיות בקהילת הקוד הפתוח Kolibri.
מקורות מידע
מקורות המידע שלי היו Kolibri, Kolibri Studio, מסמכי פיתוח RTD של Kolibri Development ו-Kolibri Toolkit מ-Google Drive.
Radina Matic הנפלאה עזרה מאוד לספק פעילויות חימום ופעילויות ספציפיות לפרויקט. הקלט שלה לגבי מה שהארגון הגדיר כ"הנחיות" ו"מדריכים", ולגבי הקיום של מדריך לתורמים, עזר לי לארגן את הרעיונות ולנסח את המסקנות שלי.
תוכנות
אני אפתח את טיוטת מדריך הסגנון ב-Google Docs. פלטפורמת המסמכים הזו מושלמת כדי לבצע איטרציה כשהיא מוכנה לפרסום. לצורך ביקורת בקרת האיכות אשתמש ב-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 בנוסף להצעות ולתגובות עם טופס ראשוני שעליו הסברתי בפירוט במשימה של בקרת ה-QA. אלו הן כמה הערות סופיות שהתקבלו מההערכה: קישורים מנותקים לאתר ICU Syntax .js הפורמט ששימש ליצירת ההנחיות האלה שגוי. המסמך הוא מדריך ולא הנחיות. חוסר עקביות בטיפוגרפיה. שימוש שגוי בכותרות ובכותרות, שימוש לא נכון בשפה ושימוש לרעה בקיצורים. שימוש בלתי הולם בטקסטים חלופיים. יותר מדי הצהרות או הוראות שחוזרות על עצמן.
הממצאים של שני המסמכים הם חלק מתוצרי ההגשה של ההצעה.
משימות ספציפיות לפרויקט
- המלצות למדריך הסגנון לתיעוד משתמש של LE (תגובות)
- הנחיות התרגום ל-LE עם סגנונות ופורמט חדשים.
- ראשי פרקים
- ציר הזמן של הפרויקט
- משימות של תיעוד