מפתחים למה אתה לא צריך לדלג תיעוד

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

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

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

תיעוד טוב מסייע למשתמשים

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

תיעוד המיועד למשתמשים בדרך כלל מורכב משימוש מעשי או “איך ל”. כלל האצבע בעת יצירת תיעוד עבור משתמשים כלליים הוא זה זה צריך להיות ברור. שימוש במילים ידידותיות לאדם עדיף על מונחים טכניים או ז 'רגון. דוגמאות שימוש אמיתי יהיה גם מוערך מאוד.

עיצוב פריסה טוב גם באמת לעזור למשתמשים לסרוק דרך כל קטע של התיעוד ללא מאמץ העין. כמה דוגמאות טובות (aka המועדפים שלי) הם תיעוד עבור Bootstrap ו WordPress ' “צעדים ראשונים עם וורדפרס”.

זה עוזר למפתחים אחרים מדי

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

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

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

מוזר זה גם עוזר את קודר

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

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

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

מה הופך לתיעוד טוב?

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

1. לעולם אל תניח

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

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

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

2. בצע את התקן

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

 / ** * הוספת שיעורים מותאמים אישית למערך של כיתות הגוף. * * @param מערך $ class שיעורים עבור אלמנט הגוף. * @ array מערך * / body_classes function ($ classes) / מוסיף מחלקה של קבוצת הבלוג לבלוגים עם יותר מ 1 מחבר שפורסם. אם (is_multi_author ()) $ classes [] = 'group-blog';  החזר $ כיתות;  add_filter ('body_class', 'body_classes'); 

להלן כמה התייחסות לעיצוב תיעוד מוטבע עם שיטות עבודה מומלצות ב- PHP, JavaScript ו- CSS:

• PHP: PHP תיעוד סטנדרטי עבור וורדפרס
• JavaScript: UseJSDoc
• CSS: CSSDoc

אם אתה משתמש SublimeText הייתי מציע להתקין DocBlockr כי יהיה מראש בקפידה לאכלס את הקוד שלך עם תיעוד inline.

3. אלמנטים גרפיים

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

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

4. חתך

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

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

5. לשנות ולעדכן

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