איך לכתוב תיעוד טכני

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

לפני שכותבים

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

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

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

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

איך לכתוב תיעוד טכני

• כתבו קודם את התוצאה. אמרו מה הקורא יוכל לעשות אחרי שהעמוד יעבוד. למשל: 'בסוף התהליך, תהיה לכם אפליקציית staging מחוברת ל Stripe.'
• השתמשו בזרימה פשוטה: מטרה, מה צריך, שלבים, תוצאה, תיקונים. כך הקורא ממשיך קדימה.
• כתבו פעולה אחת בכל שלב. 'פתחו את מסוף הניהול. בחרו Billing. בחרו Add payment method.' קל יותר לעקוב אחרי זה מאשר אחרי פסקה ארוכה עם חמישה פעלים.
• השתמשו בשמות מדויקים לכפתורים, שדות, תיקיות, פקודות, קודי שגיאה ושמות קבצים. אם המסך מציג Add payment method, אל תקראו לזה New card במסמך.
• שמרו על מונחים קבועים. אם אמרתם workspace בשלב 1, אל תעברו ל project area בשלב 4.
• שימו את הבעיה הסבירה ליד השלב שיוצר אותה. אם גישה היא לרוב הבעיה, כתבו זאת שם. למשל: 'אם הכפתור חסר, בדקו שיש לכם Billing Admin access.'
• השתמשו בדוגמאות שאפשר להעתיק, לתוכנה ולקוד. הציגו את הפקודה, ואז מיד אחריה את התוצאה הצפויה. כך הקורא יכול לבדוק מהר את המסך שלו.
• כתבו פסקאות קצרות. רעיון אחד בכל פסקה מספיק. אם יש בפסקה יותר מדי רעיונות, פצלו אותה לשתיים.
• חתכו כל דבר שלא עוזר למישהו לסיים את המשימה. רקע שימושי רק אם הוא מונע טעות.
• הוסיפו את השלב הבא בסוף. למשל, קישרו לעמוד הבדיקה, לעמוד פתרון התקלות, או לחלק ההתקנה שמגיע אחר כך.

תבנית פשוטה לשלב

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

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

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

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

מה תיעוד טכני טוב כולל

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

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

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

לעמוד הגדרה של שער תשלום, זה יכול להיראות כך: 'חברו את Stripe לאפליקציית ה staging. צריך גישת admin ומפתח בדיקה. עקבו אחרי השלבים כדי להדביק את המפתח, לשמור את ההגדרה ולהריץ חיוב בדיקה. אם הבדיקה נכשלת, בדקו את המפתח ואת הרשאות החשבון. אחר כך עברו לעמוד הגדרת ה webhook.'

בדקו לפני שמפרסמים

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

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

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

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

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

לבדיקה מהירה, עברו על tools manual check. אם אתם צריכים את אותו הרגל גם להוראות פיזיות, השוו את המבנה עם this guide.

מה בדרך כלל משתבש

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

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

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

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

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

כמה זמן זה לוקח

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

מדריך רגיל להגדרת תוכנה בדרך כלל לוקח 2 עד 4 שעות, כולל ניסוח, בדיקת השלבים ועריכה.

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

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

מתי גרסת וידאו עוזרת

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

אם כבר יש לכם manual או דף הוראות, אפשר לשים לידו גרסה מצולמת קצרה. Manual to Video הופך manual קיים לסרטון הוראות הרכבה מונפש, עם כתוביות, בצבעי המותג שלכם ועם הלוגו שלכם. הוא יכול לעבוד גם עם QR code על ה manual, על הקופסה, בדף מוצר או במאמר תמיכה.