כיצד להכין תיעוד לפרויקט?

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

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

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

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

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

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

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

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

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

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

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

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

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

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