איך כותבים תיעוד תוכנה?
להלן הוראות כיצד לכתוב תיעוד תוכנה למשתמשים טכניים ולמשתמשי קצה.
תיעוד תוכנה טוב, בין אם מסמך מפרטים למתכנתים ובודקים, מסמך טכני למשתמשים פנימיים, או מדריכי תוכנה וקבצי עזרה למשתמשי קצה, מסייע לאדם העובד עם התוכנה להבין את תכונותיה ופונקציותיה. תיעוד תוכנה טוב הוא ספציפי, תמציתי ורלוונטי ומספק את כל המידע החשוב לאדם המשתמש בתוכנה. להלן הוראות כיצד לכתוב תיעוד תוכנה למשתמשים טכניים ולמשתמשי קצה.
שיטה 1 מתוך 2: כתיבת תיעוד תוכנה למשתמשים טכניים
- 1קבע איזה מידע צריך לכלול. מסמכי מפרט תוכנה משמשים מדריכי עזר למעצבי ממשק המשתמש, למתכנתים שכותבים את הקוד ולבוחנים שמוודאים שהתוכנה עובדת כמתוכנן. המידע המדויק תלוי בתוכנית המדוברת, אך עשוי לכלול כל אחד מהבאים:
- קבצי מפתח בתוך היישום. זה עשוי לכלול קבצים שנוצרו על ידי צוות הפיתוח, מסדי נתונים אליהם הגישה במהלך הפעלת התוכנית ותוכניות שירות של צד שלישי.
- פונקציות ותת-דרכים. זה כולל הסבר מה עושה כל פונקציה או תת-דרך, כולל טווח ערכי הקלט וערכי הפלט שלה.
- משתנים וקבועים של התוכנית, ואופן השימוש בהם ביישום.
- מבנה התוכנית הכולל. עבור יישום מבוסס דיסק, פירוש הדבר של תיאור המודולים והספריות האינדיבידואליים של התוכנית, ואילו עבור יישום אינטרנט, פירוש הדבר הוא לתאר אילו דפים משתמשים בקבצים.
- 2החליטו כמה מהתיעוד צריך להיות בתוך קוד התוכנית וכמה צריך להיות נפרד ממנו. ככל שמתפתח מלכתחילה תיעוד טכני בתוך קוד המקור של התוכנית, כך יהיה קל יותר לעדכן ולתחזק את הקוד וכן לתעד גרסאות שונות של היישום המקורי. לכל הפחות, תיעוד בקוד המקור צריך להסביר את מטרת הפונקציות, תת-הדרכים, המשתנים והקבועים.
- אם קוד המקור ארוך במיוחד, ניתן לתעד אותו בצורה של קובץ עזרה, שניתן לאנדקס או לחפש באמצעות מילות מפתח. זהו יתרון מיוחד עבור יישומים שבהם לוגיקת התוכנית מקוטעת על פני עמודים רבים וכוללת מספר קבצים משלימים, כמו ביישומי אינטרנט מסוימים.
- כמה שפות תכנות, כגון Java ו-. ל- NET Framework (Visual Basic.NET, C #), יש סטנדרטים משלהם לתיעוד קוד. במקרים אלה, עקוב אחר הסטנדרטים לגבי כמות המסמכים שיש לכלול בקוד המקור.
תיעוד תוכנה למשתמשי קצה יכול להיות בצורת אחת או כמה מתוך צורות רבות: מדריכים מודפסים, מסמכי PDF, קבצי עזרה או עזרה מקוונת. - 3בחר בכלי התיעוד המתאים. במידה מסוימת, הדבר נקבע על ידי השפה בה נכתב הקוד, בין אם זה C ++, C #, Visual Basic, Java או PHP, שכן קיימים כלים ספציפיים לשפות אלו ואחרות. במקרים אחרים, הכלי לשימוש נקבע על פי סוג התיעוד הנדרש.
- תוכניות לעיבוד תמלילים עבור Microsoft Word מתאימות ליצירת קבצי טקסט נפרדים של תיעוד, כל עוד התיעוד קצר למדי ופשוט. עבור קבצי טקסט ארוכים ומורכבים, כותבים טכניים רבים מעדיפים כלי תיעוד כגון Adobe FrameMaker.
- ניתן לייצר קבצי עזרה לתיעוד קוד המקור בכל כלי ליצירת עזרה, כגון RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare או HelpLogix.
שיטה 2 מתוך 2: כתיבת תיעוד תוכנה למשתמשי קצה
- 1קבע את הסיבות העסקיות לתיעוד שלך. למרות שהסיבה הפונקציונלית לתיעוד תוכנה היא לעזור למשתמשים להבין כיצד להשתמש ביישום, ישנן גם סיבות אחרות, כגון סיוע בשיווק התוכנה, שיפור תדמית החברה ובעיקר הפחתת עלויות התמיכה הטכנית. במקרים מסוימים, יש צורך בתיעוד בכדי לעמוד בתקנות מסוימות או בדרישות חוק אחרות.
- אולם בשום מקרה, תיעוד התוכנה לא צריך להחליף תכנון ממשק לקוי. אם מסך יישום דורש מעט תיעוד כדי להסביר זאת, עדיף לשנות את עיצוב המסך למשהו אינטואיטיבי יותר.
- 2הבן את הקהל שאליו אתה כותב את התיעוד. ברוב המקרים, למשתמשי תוכנה יש מעט ידע על מחשבים שמחוץ למשימות שהיישומים בהם הם משתמשים מאפשרים להם לבצע. ישנן מספר דרכים לקבוע כיצד לתת מענה לצרכים שלהם באמצעות התיעוד שלך.
- בדוק את תארי המשרה המשתמשים הפוטנציאליים שלך. מנהל המערכת הוא מומחה סביר עם מספר יישומי תוכנה, ואילו פקיד הזנת נתונים סביר יותר לדעת רק את היישום הוא או היא משתמשת כעת כדי להזין נתונים.
- תסתכל על המשתמשים עצמם. למרות שכותרות תפקיד בדרך כלל מציינות מה אנשים עושים, יכול להיות שיש הבדל ניכר בשימוש בתארים מסוימים בארגון נתון. על ידי ראיון של משתמשים פוטנציאליים תוכלו לחוש האם רשמיכם ממה שמצביע תפקידם מעידים הם מדויקים או לא.
- עיין בתיעוד הקיים. תיעוד עבור גרסאות קודמות של התוכנה, כמו גם מפרט פונקציונלי, מספקים אינדיקציה כלשהי לגבי מה המשתמש יצטרך לדעת כדי להשתמש בתוכנית. זכור, עם זאת, שמשתמשי הקצה אינם מעוניינים באותה מידה כיצד התוכנית עובדת כמו שהם יכולים לעשות עבורם.
- זהה את המשימות הדרושות לביצוע העבודה, ואילו משימות יש לבצע לפני שניתן לבצע משימות אלה.
תיעוד תוכנה טוב הוא ספציפי, תמציתי ורלוונטי ומספק את כל המידע החשוב לאדם המשתמש בתוכנה. - 3קבע את הפורמט (ים) המתאימים לתיעוד. ניתן לבנות את תיעוד התוכנה בפורמט 1 מתוך 2, במדריך העיון ובמדריך למשתמש. לפעמים, שילוב של פורמטים הוא הגישה הטובה ביותר.
- פורמט מדריך התייחסות מוקדש להסבר על התכונות האישיות של יישום תוכנה (כפתור, לשונית, שדה ותיבת דו-שיח) וכיצד הם פועלים. קבצי עזרה רבים נכתבים בפורמט זה, במיוחד עזרה רגישה להקשר המציגה נושא רלוונטי בכל פעם שמשתמש לוחץ על כפתור העזרה על גבי מסך מסוים.
- בפורמט מדריך למשתמש מסביר כיצד להשתמש בתוכנה כדי לבצע משימה מסוימת. מדריכי משתמשים מעוצבים לרוב כמדריכים מודפסים או כקובצי PDF, אם כי חלק מקבצי העזרה כוללים נושאים לביצוע משימות מסוימות. (נושאי העזרה הללו בדרך כלל אינם רגישים להקשר, אם כי הם עשויים להיות מקושרים לקישור לנושאים שהם.) מדריכי משתמשים לעיתים קרובות לובשים צורה של מדריכים, עם סיכום המשימות שיש לבצע בהקדמה וההוראות שניתנות בשלבים ממוספרים..
- 4החליטו באיזו צורות התיעוד צריך ללבוש. תיעוד תוכנה למשתמשי קצה יכול להיות בצורת אחת או כמה מתוך צורות רבות: מדריכים מודפסים, מסמכי PDF, קבצי עזרה או עזרה מקוונת. כל טופס נועד להראות למשתמש כיצד להשתמש בכל אחת מפונקציות התוכנית, בין אם בצורה הדרכה או הדרכה; במקרה של קבצי עזרה ועזרה מקוונת, זה עשוי לכלול סרטוני הדגמה וכן טקסט וגרפיקה סטילס.
- יש לאנדקס ולחפש במילות מפתח קבצי עזרה ועזרה מקוונת כדי לאפשר למשתמשים למצוא במהירות את המידע שהם מחפשים. למרות שכלי יצירת קובצי עזרה יכולים ליצור אינדקסים באופן אוטומטי, עדיף ליצור את האינדקס באופן ידני, תוך שימוש במונחים שמשתמשים עשויים לחפש.
- 5בחר בכלי התיעוד המתאים. ניתן לכתוב מדריכים למשתמשים מודפסים או PDF בתוכנת עיבוד תמלילים כמו Word או בעורך טקסט מתוחכם כמו FrameMaker, בהתאם לאורכם ולמורכבותם. ניתן לכתוב קבצי עזרה בעזרת כלי ליצירת עזרה כמו RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix או HelpServer.
שיטה 2 מתוך 2: כתיבת תיעוד תוכנה למשתמשי קצה.
- יש לארגן את הטקסט לקריאה קלה, כאשר הגרפיקה ממוקמת קרוב ככל האפשר לטקסט המתייחס אליהם. פרקו את התיעוד לחלקים ונושאים באופן הגיוני. כל קטע או נושא צריך להתייחס לנושא יחיד, בין אם זה תכונת תוכנית או משימה אחת. ניתן לטפל בנושאים קשורים באמצעות רשימות "ראה גם" או היפר-קישורים לפי הצורך.
- לכל אחד מכלי התיעוד המפורטים לעיל ניתן להוסיף תוכנית ליצירת צילום מסך, כגון Snagit, אם התיעוד דורש מספר צילומי מסך. כמו בתיעוד אחר, יש לכלול צילומי מסך שיעזרו להסביר כיצד התוכנה עובדת, ולא כדי לסנוור את המשתמש.
- טון חשוב במיוחד, במיוחד בעת כתיבת תיעוד תוכנה למשתמשי קצה. פנה למשתמשים עם האדם השני "אתה" במקום המשתמשים של האדם השלישי. "
- כלי תיעוד תוכנה / כלי ליצירת עזרה
- כלי ליצירת מסך
שאלות ותשובות
- האם יש כלים בחינם לתיעוד תוכנה?נסה דו חמצן. אתה מגיב על הקוד שלך, מריץ Doxygen ויש לך דף אינטרנט. הוסף את LaTeX, ויש לך מסמך PDF.
- ראיתי לחיצות מקשים מתועדות במספר פורמטים. האם יש תקן ממשי לפריטים או שכולם שונים?אין תקן אוניברסלי; עם זאת, מומלץ לקבוע תקן למסמכים שלך. לקבלת כמה רעיונות, עיין במדריך הסגנון של מיקרוסופט (זמין באמזון) ובמדריך הסגנון של אפל (help.apple.com/applestyleguide/). יש להם סגנונות שונים, כך שאם אתה כותב תיעוד חוצה פלטפורמות, אתה עלול להשתמש באלמנטים מסוימים ממדריך אחד וחלקם אחר.
