תיעוד משתמש: מה עושה את זה רע ואיך לתקן את זה

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

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

בעיה 1: מאמרים לא ברורים, כתובים בצורה גרועה

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

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

שקול את הטיפים שלמעלה, והמאמרים יתבהרו - מובטח. כדי לעשות את זה אפילו טוב יותר, השתמש שלנו 50 שאלות בעבודה על תיעוד טכני.

בעיה 2. מאמרים לא עונים על כל השאלות

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

התיעוד לא עומד בקצב הפיתוח

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

ביצענו שינויים ב-YouTrack. המשימה של כתיבת מאמר על פיצ'ר חדש נופלת על הכותב הטכני באותו רגע שבו הפיצ'ר מתחיל להיבדק. לאחר מכן שיווק לומד על זה כדי להתכונן לקידום. הודעות מגיעות גם ל-Mattermost הארגונית, כך שפשוט אי אפשר לפספס חדשות ממפתחים.

התיעוד אינו משקף את בקשות המשתמש

אנחנו רגילים לעבוד ככה: יצא פיצ'ר, דיברנו עליו. תיארנו כיצד להפעיל אותו, לכבות אותו ולבצע התאמות עדינות. אבל מה אם לקוח משתמש בתוכנה שלנו בצורה שלא ציפינו? או שיש לו שגיאות שלא חשבנו עליהן?

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

התיעוד אינו בשיפור

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

יש לנו קבוצה בפורטל הפנימי שבה העובדים משאירים הערות, הצעות ורעיונות על תיעוד. האם תמיכה צריכה מאמר, אבל היא לא קיימת? האם הבוחן שם לב לאי הדיוק? האם השותף התלונן בפני מנהלי פיתוח על טעויות? הכל בקבוצה הזו! כותבים טכניים מתקנים כמה דברים מיד, מעבירים כמה דברים ל-YouTrack ונותנים לאחרים קצת זמן לחשוב עליהם. כדי למנוע מהנושא לגווע, מדי פעם אנו מזכירים לכם את קיומה של הקבוצה ואת חשיבות המשוב.

בעיה 3. לוקח הרבה זמן למצוא את המאמר הנכון.

מאמר שלא ניתן למצוא אינו טוב יותר ממאמר שלא ניתן למצוא. המוטו של תיעוד טוב צריך להיות "קל לחיפוש, קל למצוא." איך להשיג זאת?

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

1. מתוך הממשק. התוכן משכפל את חלקי הפאנל. זה היה המקרה בתיעוד הישן של ISPsystem.
2. מתוך משימות. כותרות המאמרים והמדורים משקפים את משימות המשתמשים; כותרות מכילות כמעט תמיד פעלים ותשובות לשאלה "איך לעשות". עכשיו אנחנו עוברים לפורמט הזה.

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

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

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

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

בצד ימין בחלון המוקפץ יש קישור למאמר על הגדרת DNSSEC בחלק ניהול הדומיין של ISPmanager

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

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

בעיה 4. פריסה מיושנת מפריעה לתפיסה

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

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

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

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

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

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

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

פורמטים. שלב כמה פורמטים במאמרים שלך: טקסט, וידאו ותמונות. זה ישפר את התפיסה.

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

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

איפה להתחיל לשפר ואיך לשרוד

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

נגיד מיד - זה לא יהיה קל. וגם לא סביר שזה יעבוד מהר. אלא אם כן אתה רק מתחיל ועושה את הדבר הנכון מיד. דבר אחד שאנחנו יודעים בוודאות הוא שזה ישתפר עם הזמן. אבל התהליך לעולם לא יסתיים :-).

מקור: www.habr.com