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

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

מפה קטנה של מקום גדול

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

פקודות שאפשר להריץ

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

גבולות שיש להם סיבה

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

הגדרת סיום

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

תבנית התחלה

מוצר: [משפט אחד]
מפת מאגר: [תיקיות וקישור לארכיטקטורה]
הקמה מקומית: [פקודה ודרישות]
אימות שינוי: [בדיקות לפי תחום]
גבולות: [כלל, סיבה ודוגמה]
דיווח בסיום: [מה השתנה, מה נבדק, מה חסר]

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

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