جدول المحتويات

أنواع المستندات

فيما يلي توضيح مختصر لأنواع مساهمات المستندات المقبولة على amp.dev

البرنامج التعليمي التمهيدي

تساعد البرامج التعليمية التمهيدية المطور في فهم الفكرة العامة للتكنولوجيا. وتبدأ معهم من تعليم الترميز وتنتهي بمشروع "Hello World” الأساسي الكامل. تشرح البرامج التعليمية التمهيدية كيفية بناء ميزة رئيسية لـ AMP من خلال عملية خطوة بخطوة. ويمكن إقران البرامج التعليمية التمهيدية بأمثلة ترميز مدمجة و/أو أمثلة قابلة للتنزيل تتطلب من المطور أدنى قدر من التعديلات لتشغيلها.

أمثلة amp.dev:

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

البرنامج التعليمي المتقدم

تساعد البرامج التعليمية المتقدمة المطورين في تنفيذ مهمة خاصة. وتفترض أن المطور على دراية بـ AMP. ويجب أن توضح كيفية بناء تجربة أو دمج ميزة أو معالجة مهام التنفيذ.

أمثلة amp.dev:

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

الدليل التمهيدي

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

أمثلة amp.dev:

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

دليل المفاهيم

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

أمثلة amp.dev:

افعل	لا تفعل
توفير جميع العناصر اللازمة للمطور لبناء الحل.	توجيه المطور بفعالية إلى حالة نهائية معينة.
تغطية كافة نواحي الموضوع.	التركيز على مهمة معينة.
تضمين وسائل مساعدة مرئية مثل الرسومات البيانية أو لقطات الشاشة .	المبالغة في هذا الأمر، يمكنك طلب مساعدة بشأن الوسائل المساعدة المرئية من [مجموعة أعمال التوعية](https://github.com/ampproject/wg-outreach).
توفير أمثل ترميز والربط بالأدلة الأخرى.	توفير تنزيل لمشروع نهائي أو موضوع مشتت.

المستندات المرجعية

تسرد المستندات المرجعية كافة العناصر البرمجية لمكون AMP. وتوفر معلومات سلوكية تفصيلية كما أنها مصممة ليسهل فحصها. ويجب أن تشتمل المستندات المرجعية على أمثلة ترميز توضيحية وتشرح حالات الاستخدام.

توجد المستندات المرجعية لـamp.dev تحت كتالوج مكونات AMP.

تسهم مستندات AMP المرجعية في مستودع AMPHTML .

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

Written by @CrystalOnScript