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