טיפים שימושיים

תיעוד טכני

Pin
Send
Share
Send
Send


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

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

שיטה 1 מתוך 2: כתיבת תיעוד לטכנאים

  1. החליט איזה מידע לכלול.. מפרט התוכנה משמש מדריכים למפתחי ממשקים, מתכנתים שכותבים קוד ובודקים שמוודאים כי התוכנית עובדת כמתוכנן. המידע המדויק תלוי בתוכנית, אך עשוי לכלול את הפריטים הבאים:
  • קבצי יישום מרכזיים. אלה עשויים לכלול קבצים שנוצרו על ידי צוות הפיתוח, בסיסי נתונים שאליהם ניגשים במהלך ביצוע התוכנית, ושירותי צד שלישי.
  • פונקציות ושגרה. הם כוללים הסבר על מה שעושה כל פונקציה או תת-רוטינה, כולל טווח של ערכי קלט ופלט.
  • משתני תוכנית קבועים וכיצד משתמשים בהם ביישום.
  • המבנה הכולל של התוכנית. עבור גרסת הדיסק של היישום, זה עשוי להיות תיאור של המודולים והספריות הבודדות של התוכנית. עבור יישום אינטרנט, אינדיקציה לאילו דפים מקשרים לאילו קבצים.
  1. החלט כמה תיעוד אתה צריך לכלול בקוד התוכנית, וכמה צריך להיות נפרד ממנו.. ככל שפותח תיעוד טכני יותר בתוך קוד המקור של התוכנית, כך יהיה קל יותר לעדכן ולתחזק אותו יחד עם הקוד, כמו גם לתעד גרסאות שונות של היישום המקורי. לכל הפחות, התיעוד בקוד המקור אמור להסביר את מטרת הפונקציות, השגרה, המשתנים והקבועים.
  • אם קוד המקור ארוך במיוחד, ניתן לתעד אותו כקובץ עזרה שתוכל להוסיף לו אינדקס או לבצע חיפוש מילות מפתח. זה נוח במיוחד ליישומים שבהם לוגיקת התוכנית מחולקת למספר עמודים וכוללת מספר קבצים נוספים, כמו יישומי אינטרנט מסוימים.
  • לחלק משפות תכנות, כמו Java ו- .NET Framework (VisualBasic .NET, C #), יש סטנדרטים משלהם לתיעוד קוד. במקרים אלה, עקוב אחר התקנים הנוגעים לאיזה חלק מהתיעוד שצריך לכלול בקוד המקור.
  1. בחר בכלי התיעוד המתאים. במידה מסוימת זה נובע מהשפה בה כתוב הקוד, בין אם זה C ++, C #, Visual Basic, Java או PHP, מכיוון שיש כלים ספציפיים לשפות אלו ושפות אחרות. במקרים אחרים, הכלי לשימוש תלוי בסוג המסמכים הנדרש.
  • די בעורכי טקסט של Microsoft Word כדי ליצור קבצי תיעוד טקסט נפרדים, בתנאי שהתיעוד קצר למדי ופשוט. עבור קבצי טקסט ארוכים ומורכבים, סופרים טכניים רבים מעדיפים כלי תיעוד מיוחד, כגון Adobe FrameMaker.
  • ניתן ליצור קבצי עזרה לתיעוד קוד המקור בכל כלי לכתיבת עזרה: RoboHelp, עזרה ומדריך, Doc-to-Help, MadCap Flare או HelpLogix.

כיצד לכתוב תיעוד טכני?

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

איך לכתוב טקסט "שקוף" ומובן של תיעוד טכני בכלל?

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

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

עכשיו על ההבנה. הבנה היא מכלול המאפיינים של כלי תוכנה המאפיין את עלות מאמצי המשתמש להבין את התפיסה ההגיונית של כלי תוכנה זה. הערה - המושג הלוגי פירושו מושגי היסוד, העקרונות וההסכמים המעניקים למערכת הכללים לעבודה עם תוכנה אופי עקבי וסביר ומאפשרים לך לקבוע במדויק באופן הגיוני את המטרה והתוכן הספציפי של כללים אלה [מתוך אפליקציה סעיף 3.1. 2 GOST 28806-90].

כלי תוכנה הוא שילוב של תוכנית לתיעוד הנלווה לה, ולכן ההבנות של תוכנית הינה די מתאימה הן לתיעוד התוכנית והן לתיעוד הטכני בכללותו.

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

איך לכתוב טקסט מובנה?

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

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

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

  1. שאלה ראשונה: "מה כתוב בביטוי המבוא?" תשובה: "משתני AuthorIT נועדו:",
  2. שאלה שנייה: "מה כתוב בפסקה הראשונה ברישום?" תשובה: ". לאחסון שברי טקסט, אלמנטים גרפיים וכו '. "
  3. שאלה שלישית: "אז בשביל מה משתנים AuthorIT? קרא את משפט היכרות ואת הפסקה הראשונה ברישום במשפט אחד ",
  4. .
  5. והשאלה האחרונה (מכה רצחנית): "מה לא צפוי ?!"

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

על היתרונות של הכנסת טקסטים אותנטיים של GOST ומסמכי רגולציה אחרים בתיעוד טכני

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

כנראה להסביר את השבר הנתון של הספר במילים ולא. עדיף לספר מקרה מעניין מהחיים.

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

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

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

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

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

כתב את המסמך הטכני בצורה נכונה - ותוכל להתעורר לכולם

דר. הסבר

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

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

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

GhostDoc הוא תוסף ל- Visual Studio בעזרתו תוכלו לייצר בקלות הערות מסמכי XML. הכלי מייצר הערות המבוססות על מספר גורמים, כולל שם, פרמטרים, מידע על הקשר, סוגים וכו '.

מפות טבעיות

Natural Docs הוא כלי נוסף עם קוד פתוח שעובד עם שפות תכנות רבות. זה יעזור לך להפוך את תיעוד הקוד לאוטומטי ולהמיר אותו לפורמט HTML. נכון לעכשיו, NATURAL DOCS תומך ב -19 שפות תכנות, כולל Python, C ++, PL / SQL, Actionscript וכו '.

דוקטורנט

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

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

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

דמיאן וולף דן בנושא זה ביתר פירוט במאמר "מדוע מפתחים כותבים תיעוד מחריד ואיך לפתור אותו".

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

Pin
Send
Share
Send
Send