בדף הזה מופיעים הפרטים של פרויקט כתיבה טכנית שהתקבל בעונה של Docs ל-Google Docs.
סיכום הפרויקט
- ארגון קוד פתוח:
- HPX
- כותבים טכניים:
- rstobaugh
- שם הפרויקט:
- עריכה וייעול של מסמכי התיעוד הקיימים של HPX
- אורך הפרויקט:
- אורך סטנדרטי (3 חודשים)
תיאור הפרויקט
ההצעה שלי היא לערוך את התוכן הקיים של מסמכי התיעוד של HPX ולייעל אותו. ההצעה שלי היא לפרויקט לטווח רגיל (שלושה חודשים) שמתמקד בשינוי שני פרקים במדריך של קבוצת STE||AR: ""HPX Build System and Launching"" (1) ו-""Configuring HPX Applications"" (2).
בפרק 'מערכת ה-build של HPX והפעלה' יש כמה שגיאות דקדוקיות, והוא מכיל גם שפה מבלבלת ושימוש לא עקבי באותיות רישיות במונחים כמו 'CMake'. בנוסף, הוא מכיל מידע שחוזר על עצמו, ואני מתכוון לסדר מחדש, לאחד ולקצץ אותו לפי הצורך. הפרק 'הגדרת אפליקציות HPX' מכיל גם כמה שגיאות דקדוק שצריך לטפל בהן, אבל הבעיה העיקרית שלי עם הפרק הזה היא שהוא לא ידידותי למשתמש. הפרק כולל שלוש בעיות עיצוב עיקריות שאני מתכוון לטפל בהן:
חלק מהכותרות קבורות בתוך הטקסט, מה שמקשה על דפדוף בפרק. נכון לעכשיו, המשתמשים צריכים לקרוא בעיון את המדריך כדי להבין את המטרה של כל טבלה. זו לא הדרך שבה רוב המשתמשים מקיימים אינטראקציה עם מדריכי הוראות, במיוחד אם הם כבר קראו את התוכן בעבר. במקום זאת, אקפיד שלכל טבלה תהיה כותרת ברורה ומובחנת, שאפשר יהיה לראות בקלות אם המשתמש יגלול את הטקסט.
כשמציגים נכסים שונים בכותרת מסוימת, הנכסים לא מופיעים בסדר לוגי. הנכסים מקובצים לפי נושא משותף, אבל אין חלוקה לקבוצות משנה, ולכן המידע נראה מפוזר. לדוגמה, משתמש עשוי להיתקל בכמה נכסים שעוסקים במיקום, בכמה נכסים שעוסקים בנושא אחר, ואז בנכס נוסף שעוסק במיקום. היעדר המבנה הפנימי בכותרות מקשה על איתור כל המידע בנושא משני ספציפי. לכן, אני מתכנן לארגן מחדש כמה מהתרשימים כדי לקבץ מידע דומה בצורה ברורה יותר תחת כל כותרת.
המשתמשים נאלצים לנווט הלוך ושוב בין קטעים (או לפתוח את המדריך בשתי כרטיסיות נפרדות) כדי להבין באופן מלא הוראות מסוימות. יש נקודות שבהן הפרק מפנה את המשתמשים למשפט אחד מתוך קטע קודם באופן שמאלץ את הקורא לגלול למעלה או ללחוץ על היפר-קישור כדי להבין את ההוראה המדויקת, כי המדריך כתוב בניסוח לא ברור כמו "השלב הזה נוצר אחרי שלב 11" בקטע הקודם. השיטה הזו מבטלת חזרות, אבל קשה יותר להבין את ההוראות. אלה משימות שצריך להגדיר לפי סדר מסוים. במקום זאת, מומלץ לכלול ניסוח ספציפי יותר כדי שהמשתמשים לא יצטרכו להפסיק את תהליך הקריאה כדי לעבור בין קטעים או מסמכים.
אם אשלימ את החלקים האלה לפני שהתזמון הרגיל יסתיים, אשמח גם לנקות את הדף 'למה HPX?' (3) בקטע 'מסמכי העזרה למשתמש' של קבוצת STE||AR. הדף הזה מכיל תוכן מבוא חוזר על עצמו, ואני מקווה לאחד אותו. הוא מכיל גם חוסר עקביות בשימוש באותיות רישיות (במיוחד בז'רגון) ובסגנון, מה שגורם לתחושה של חוסר אחידות. המטרה שלי היא ליצור מבוא מאוחד ועקבי יותר לעבודה של קבוצת STE||AR.