مثال واحد في الأمر: متى يكفي لتوضيح التنسيق؟

الخلاصة السريعة

استعمل مثالا واحدا لإيضاح شكل بسيط، ثم افحص مدخلا مختلفا؛ إذا بقيت قاعدة أو حالة ناقصة، وضحها قبل زيادة الأمثلة.

• اعرض مدخلا ومخرجا مترابطين؛ تصف AWS الأمثلة داخل الأمر بهذه الصورة. ^[1]
• حدد ما يتكرر من البنية وما يستبدل من البيانات، حتى لا تصبح تفاصيل المثال معلومات للمهمة الجديدة.
• راجع مدخلا مختلفا عن المثال؛ نجاح الشكل لا يثبت صحة الحقول أو تغطية الحالات الناقصة.
• أضف مثالا عند وجود فرق يحتاج توضيحا، لا لمجرد بلوغ عدد ثابت من الأمثلة.

أظهر التحويل الذي تقصده

توضح AWS أن أمثلة المدخل والاستجابة تعرض طرق أداء المهمة. لا نستنتج من ذلك أن مثالا واحدا يكفي دائما. ^[1]

مثال مستقل لبطاقة كتاب افتراضي: المدخل «العنوان: نافذة الحديقة؛ النوع: قصة». المخرج المطلوب «نافذة الحديقة | قصة». تستطيع كتابة أمر: «حوّل كل بطاقة إلى سطر فيه العنوان ثم النوع، وبينهما العلامة |». المثال يوضح موقع الفاصل وترتيب الحقلين، والقاعدة تبين المطلوب بالكلمات.

افصل الشكل عن بيانات المثال

لو كان المدخل الجديد «العنوان: خريطة النهر؛ النوع: كتيب»، فالسطر المقترح هو «خريطة النهر | كتيب». الاسم والنوع الجديدان مأخوذان من البطاقة الجديدة، وليسا نسخة من بطاقة القصة. هذه مقارنة كتبناها للشرح؛ لم نجربها على نموذج.

قل صراحة إن المثال لتوضيح التنسيق فقط. وإذا أردت إبقاء نوع الكتاب كما ورد دون استنتاجه من العنوان، فحدد ذلك أيضا. لا يثبت الاسم «خريطة» أن الكتاب علمي أو جغرافي؛ المطلوب نقل حقل النوع، لا تخمين محتواه من اسم جذاب.

افحص ما يحدث خارج المثال

راجع بطاقة أخرى يتغير فيها طول العنوان أو توجد علامة ترقيم. هل بقي كل عنوان في حقله، وهل ظهر فاصل واحد في الموضع المقصود؟ افحص البيانات كذلك: نجاح السطر في تقليد الشكل لا يعوض تغيير «كتيب» إلى «قصة».

إذا كانت بطاقة بلا نوع، فالمثال الأول لا يخبرنا هل نترك الحقل فارغا أو نكتب «غير مذكور» أو نسأل. اختر التعامل مع النقص وفق غرضك. لا تدع العدد الصغير من الأمثلة يخفي غياب القرار، ولا تتوقع أن يستنبط المساعد قاعدة واحدة صحيحة من بطاقة مكتملة فقط.

أضف ما يوضح فرقا حقيقيا

يمكن إضافة بطاقة ناقصة تبين التعامل المطلوب معها، أو بطاقة يحتوي عنوانها الفاصل نفسه إذا كان ذلك واردا. راجع هل ما زال السطر مناسبا أم يحتاج شكلا آخر يحفظ حدود الحقول. المثال الإضافي ينبغي أن يجيب عن سؤال جديد، لا يعيد أسماء أخرى في البنية نفسها.

احتفظ بالتعليمات والأمثلة التي راجعتها، وسجل الحالات التي بقيت دون قرار. وقد يكون وصف مباشر كافيا لبعض التحويلات دون أي مثال. المقصود تقليل الالتباس بمادة مفيدة، لا إثبات أن طريقة المثال الواحد تتفوق على كل بديل أو أن المحاولة الناجحة تكفي للاعتماد العام.