פרויקט Kolibri

בדף הזה מופיעים הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Docs ל-Google Docs.

סיכום הפרויקט

ארגון קוד פתוח:
Kolibri
כותבים טכניים:
StephDix
שם הפרויקט:
הסכמי סגנון ותהליכי עבודה של מסמכי העזרה של הסביבה העסקית של Kolibri
אורך הפרויקט:
Long running (5 months)

תיאור הפרויקט

מופשט

במסמך הזה מפורטת ההטמעה של הנחיות הסגנון ושל ניהול תהליך העבודה במידע המתוועד של Learning Equality בפרויקט Kolibri Ecosystem.

סקירה כללית

ההצעה שלי מורכבת מארבעה שלבים. בשלב הראשון, אשליך אור על מדריך הסגנון של מסמכי העזרה של LE בהנחיות לגבי נגישות, כתיבה ופורמט, בהתאם למושגים ולמדריך הסגנון של LE בפיתוח תוכנה. בשלב השני, אבדוק את האיכות של מסמכים ב-ReadTheDocs וב-Google Docs. תוכנית הביקורת כוללת שימוש ברשימות משימות כדי לבדוק את התאימות להנחיות הסגנון. רשימות המשימות האלה יעזרו לתעד את הממצאים ולהחיל שינויים במסמכים. בשלב השלישי אעבוד על המבנה, המראה והתחושה של התבניות ממסמכים ב-ReadTheDocs וב-GoogleDocs. אצור מאגר של תבניות ותמונות ב-Google Drive, שבו לכל קטגוריית תבניות של סוגי מסמכים עיקריים תהיה תווית, כדי שנוכל להשתמש בהן שוב בהטמעות הבאות. אשלים את המשימה הזו על ידי יצירת תבניות לשליחת בעיות במסמכים, כדי שיהיה קל לזהות אותן בבדיקות של בקשות משיכה. לבסוף, אצור מדריך לתורמים שבו אקבץ משאבים שימושיים לכל קבוצה של שותפים לעריכה, כדי לשפר את חוויית הגישה שלהם למידע.

מטרה והיקף

מטרת תוכנית ההטמעה הזו היא לשפר את חוויית המשתמשים הקצה שמשתמשים במסמכים של Kolibri, ולעזור לחברי הצוות ולתורמים ליצור תיעוד טוב יותר ולשתף פעולה באופן פעיל בקהילה. ההטמעה הזו חלה על ReadTheDocs ועל קבוצות משנה של מסמכים ב-Google Docs בסביבת Kolibri.

קהל

קהל ראשי של מפתחים, אדמינים ומשתמשי קצה, שהם הצרכנים החשובים ביותר של מסמכי התיעוד של Kolibri. קהל משני של חברי צוות ושותפים ליצירה, לצורך הפקת תיעוד Kolibri ושימוש בו.

מטרות

לפי מדריך הסגנון ומערכת תהליך העבודה של מסמכי התיעוד של סביבות העבודה של Kolibri, המשתמשים צריכים: ליצור מסמכי תיעוד שקל לעכל, עם שפה נגישה ופריסה עקבית. שמירה על שיטות איכות בתיעוד. שמירה על נוחות הגישה למידע בין ערוצי התיעוד. לחזק את יוזמות השיתוף פעולה בקהילה של קוד המקור של Kolibri.

מקורות מידע

מקורות המידע שלי היו Kolibri,‏ Kolibri Studio, מסמכי RTD של Kolibri Development ו-Kolibri Toolkits מ-Google Drive.
Rרדינה מטיק הנפלאה עזרה מאוד לתחזק פעילויות חימום ופעילויות ספציפיות לפרויקט. המידע שהיא מספקת על מה שהארגון מחשיבה כ"הנחיות" ו"מדריכים" ובנוגע לקיומו של 'מדריך לתורמים' עזר לי לארגן את הרעיונות שלי ולנסח מסקנות.

תוכנה

אני אפתח את הטיוטה של מדריך הסגנון ב-Google Docs. פלטפורמת המסמכים הזו מושלמת ליצירת גרסאות חלופיות בזמן שהמסמך מוכן לפרסום. לבדיקת בקרת האיכות, אשתמש ב-Google Forms כדי לבצע את הבדיקה ולהעריך את המסמכים. התשובות מהטופס יישמרו בגיליון אלקטרוני לצורך בקרה על המסמכים. אשלב מחדש מסמכי RTD באמצעות GitHub. עבדתי עם Git,‏ Gitkraken,‏ GitHub ו-Gitlab. יש לי ידע בעבודה עם Markdown ועם כמה פורמטים של RestructuredText. אני מתכנן לתרום לתיקונים במסמכי העזרה כדי להמשיך ללמוד את התחביר. אשתמש ב-Sharex לתמונות ולקובצי GIF. אני אוהב את הכלי הזה מפני שהוא מעובד בפורמטים שונים של פלט. אשתמש ב-Diagrams ליצירת תרשימים ולעריכת תמונות. תוכנת Diagrams משתלבת בצורה מושלמת עם Google Docs,‏ Google Drive ו-LibreOffice. מצב המסמכים בשלב הבדיקה, שיפרתי את רוב המסמכים של Kolibri. מצאתי שגיאות דקדוק, שגיאות כתיב, חוסר עקביות בפריסה, בטיפוגרפיה, בשימוש בתמונות וגם נתיבים מבלבלים במסמכי העזרה ברוב המסמכים של הפרויקט. לדוגמה, במדריך למשתמש של Kolibri, הקטע 'פתרון בעיות' הוא נושא משנה ולא נושא. המידע הזה חיוני מספיק כדי שמשתמשי הקצה יוכלו לגשת אליו דרך תוכן העניינים. לחלופין, הם יכולים להשתמש בסרגל החיפוש ובעץ של תוכן העניינים כדי להרחיב נושאים אחרים ולמצוא מאמרים בנושא פתרון בעיות.

כדי לגשת לקטע 'פתרון בעיות', צריך לחפש אותו או להרחיב את הקטע 'ניהול Kolibri' כדי להבין שפתרון בעיות נכלל במסמכי העזרה. מדריך לעומת הנחיות עבור הצעת הפרויקט הזו, ניתחתי שני מסמכים: LE Kolibri User Material Style Guide ו-LE Translate Guidelines (הנחיות לתרגום LE). ב-LE Kolibri Guide, הצגתי המלצות ותגובות בהתאם למתאר הנושא ולתוכנית המסמכים שהצעתי, ועוד כמה דברים שצריך לשפר במדריך. בהנחיות לתרגום של LE, שיניתי את הפורמט והסגנון על סמך ההמלצות שלי והמוסכמות הקיימות במדריך הסגנון. במהלך הניתוח, הבחנתי בעיקר בהבדל בין מסמכים שמסווגים כ'מדריך' לבין מסמכים שמסווגים כ'הנחיות'.

תוצאות

ביצעתי בדיקת איכות למדריך התרגום של LE, בנוסף להצעות ולתגובות בטופס ראשוני, שאסביר בפירוט במשימה של ביקורת בקרת האיכות. אלה כמה הערות סופיות שהתקבלו מהבדיקה: קישורים לא תקינים לאתר ICU Syntax ‎ .js הפורמט שבו השתמשתם ליצירת ההנחיות האלה שגוי. המסמך הוא מדריך, ולא הנחיות. טיפוגרפיה לא עקבית. שימוש שגוי בכותרות ובשמות, שימוש לא נכון בשפה ושימוש שגוי בקיצור מילים. שימוש לא תקין בטקסטים חלופיים. על הצהרות או הוראות חוזרות.

הממצאים בשני המסמכים הם חלק מהמסמכים שצריך לספק בהצעה הזו.

משימות ספציפיות לפרויקט

  • המלצות למדריך הסגנון למשתמש של LE (הערות)
  • הנחיות התרגום של LE עם סגנונות ופורמט חדשים.
  • תוכנית נושא
  • ציר הזמן של הפרויקט
  • משימות בנושא תיעוד