WikiHow זה מלמד אותך כיצד לכתוב תיעוד לפרויקט קוד פתוח. תיעוד זה מכונה בדרך כלל קובץ README. ה- README הוא טקסט או מסמך HTML המכיל מידע חשוב הן למשתמשים והן למפתחים אודות הפרויקט שלך.
צעדים
שלב 1. כתוב את הכותרת לפרויקט שלך
בעת כתיבת README לפרויקט שלך, הדבר הראשון שאתה צריך לכלול הוא שם הפרויקט. יחד עם הכותרת, עליך לכלול גם את מספר הגירסה העדכני ביותר ואת התאריך שבו הוא עודכן לאחרונה.
שלב 2. כתוב תיאור של הפרויקט שלך
הדבר הבא שעליך לכלול ב- README שלך הוא תיאור קצר של הפרויקט שלך. הסבר מה הפרויקט עושה, מדוע הוא קיים ואילו בעיות הוא פותר. אתה יכול גם לכלול כל תכונות מיוחדות, צילומי מסך, סגנון קוד, טכנולוגיה או מסגרת בשימוש, או כל דבר אחר שיעזור למשתמשים ולמפתחים.
שלב 3. הסבר את כל הדרישות שיש לפרויקט שלך
אם הפרויקט שלך זקוק לדרישות מיוחדות על מנת לפעול כראוי, הקפד לרשום את הדרישות וההוראות האלה, או קישור להוראות כיצד להתקין אותן.
שלב 4. כלול דוגמא של הקוד
ספק דוגמא ברורה ותמציתית למה משמש הפרויקט שלך. הקוד צריך להיות קל למפתחים להבין, וה- API צריך להיות גלוי בבירור.
שלב 5. ספק הוראות התקנה
הסבר למשתמשים כיצד להפעיל את התוכנה שלך בפורמט שלב אחר שלב. ההנחיות שלך צריכות להיות ברורות ככל האפשר. נניח שלמשתמשים שלך אין ידע בפיתוח תוכנה או בניהול מערכת.
שלב 6. הסבר כיצד להשתמש בתוכנה
ספר לאנשים כיצד להפיק את המרב מהתוכנה שלך. ספק הוראות שלב אחר שלב כיצד להשתמש בתוכנה שלך, כמו גם אפשרויות תצורה שונות וכיצד להגדיר אותן.
שלב 7. ספר למשתמשים כיצד לקבל סיוע טכני
מספק קישורים לכל רשימות דיוור, ערוצי IRC או פורומים קהילתיים שאליהם משתמשים יכולים לפנות לקבלת סיוע טכני. הודע גם למשתמשים מנוסים יותר היכן לשלוח באגים ורעיונות כדי להפוך את הפרויקט לטוב יותר.
אם אתה מוצא שאתה מקבל הרבה אותן שאלות ממשתמשים שונים, מומלץ לכלול שאלות נפוצות (שאלות נפוצות) כחלק מתיעוד הפרויקט שלך
שלב 8. הסבר כיצד לתרום
אם אתה עובד על פרויקט קוד פתוח, הודע למשתמשים שלך כיצד הם יכולים לתרום לפרויקט שלך. הסבר את כל הסטנדרטים שיש לך וספק כמה הנחיות לתורמים פוטנציאליים.
שלב 9. רשום את הזיכויים
תמיד לתת אשראי במקום אשראי מגיע. הקפד לרשום את השמות של כל התורמים, כמו גם קישורים לכל ספריות או תוכניות של צד שלישי שבהן השתמשת. כלול קישורים לכל השראה שהייתה לך בעת בניית הפרויקט שלך.
שלב 10. ספק את פרטי הקשר שלך
אנשים עשויים לרצות ליצור איתך קשר מכל מיני סיבות. הקפד לספק כתובת דוא ל חוקית שאנשים יכולים להשתמש בה כדי ליצור איתך קשר.
מדינות מסוימות עשויות לדרוש מידע נוסף, כגון כתובת דואר או שם חברה על פי חוק
שלב 11. ספק פרטי רישיון
חשוב למשתמשים לדעת כיצד הפרויקט שלך מורשה. יש הרבה רישיונות סטנדרטיים ברחבי האינטרנט שאתה יכול להשתמש בהם. הסבר באיזה רישיון הפרויקט שלך משתמש, כמו גם הרשיונות של כל ספריות או תוכניות של צד שלישי שבהן אתה עשוי להשתמש.
אינך צריך להסביר את כל הרישיון בתיעוד שלך. רק יידע את המשתמשים באיזה רישיון הפרויקט שלך משתמש, וספק קישור למידע על הרישיון המלא
שלב 12. רשום את כל הגרסאות של הפרויקט
הקפד ליצור רשימה של כל הגרסאות הקודמות של הפרויקט שלך וכתוב תיאור קצר של אילו עריכות ביצעת עבור כל גרסה.
טיפים
- זה מנהג טוב להתחיל לכתוב את קובץ ה- README שלך לפני שתתחיל לפתח את הפרויקט שלך. זה יעזור לך לחשוב על הפרויקט שלך ועל מה שאתה צריך להשיג. זה יעזור לך לפתח קווים מנחים שתוכל לתקשר לתורמים אחרים, ותהיה לך מוטיבציה רבה יותר לכתוב את קובץ ה- README שלך בתחילת הפרויקט.
- הקפד לעדכן את קובץ ה- README שלך ותיעוד אחר לעתים תכופות בזמן שאתה עובד על הפרויקט שלך.
- אם קובץ ה- README שלך ארוך מדף בערך, באפשרותך לכתוב את החלקים הארוכים יותר, כגון הוראות התקנה, מדריך למשתמש ושאלות נפוצות כמסמך נפרד. הקפד ליצור תוכן עניינים עבור כל תיעוד הפרויקט שלך ולספק קישור לתיעוד המתאים בקובץ README.