المرحلة الحالية:
انتهى برنامج Season of Docs لعام 2020 في 15 آذار (مارس) 2021. اطّلِع على
المخطط الزمني.
تحتوي هذه الصفحة على إرشادات للكتّاب التقنيين حول كيفية إنشاء تقرير مشروعك عندما تنتهي من عملك لموسم Season of Docs لهذا العام.
تقديم تقرير المشروع
عند فتح مرحلة الانتهاء من المشروع، ستتمكن من إرسال تقرير مشروعك من خلال إكمال نموذج يصبح متاحًا في قسم إكمال المشروع من دليل الكاتب الفني.
المعلومات المراد تضمينها في تقرير المشروع
يصف هذا القسم نوع المعلومات التي يمكنك توفيرها في تقرير المشروع لديك. سيتضمن نموذج تقرير المشروع حقولاً ذات نص حر بالإضافة إلى أسئلة متعددة الخيارات.
الربط بعملك
قم بتوفير رابط يشير إلى وصف العمل الذي أنجزته.
يجب أن يشير الرابط إلى مستند يحتوي على وصف موجز للعمل المنجز والوثائق التي دمجها المشروع مفتوح المصدر في مستودعه وملخصًا للحالة الحالية للمشروع وقائمة بالتحديات والدروس المستفادة.
وسيظهر الرابط في نتائج "موسم المستندات" المنشورة على الموقع الإلكتروني. توضح النتائج المنشورة العمل الذي أنجزته خلال البرنامج. تعد النتائج المنشورة أيضًا طريقة رائعة بالنسبة لك للرجوع إلى عملك كجزء من سيرتك الذاتية.
يجب عليك مشاركة الرابط الخاص بك مع مرشدك وطلب المراجعة قبل تقديم تقرير مشروعك.
متطلبات تقرير مشروعك
يجب وضع المتطلبات التالية في الاعتبار:
- يجب أن يسهّل المحتوى المرتبط إمكانية تحديد العمل الذي أنجزته خلال "موسم المستندات"، أي التغييرات التي أجريتها أو الوثائق الجديدة التي كتبتها.
- يجب وضع العمل في موقع ثابت. لا يمكنك تغيير عنوان URL بعد الإرسال.
من المفترض أن يتمكّن شخص آخر من استخدام المحتوى في هدف الرابط (أو المشار إليه من) للبناء على عملك.
- إذا كان عملك مكتملاً بنسبة 100٪، يجب أن يتمكن الأشخاص الآخرون من استخدامه.
- إذا لم يكتمل عملك بنسبة 100٪، فيجب أن يكون واضحًا ما المتبقي للقيام به.
أمثلة جيدة على كيفية وصف عملك
ليس عليك القيام بكل (أو أي) هذه الأشياء، ولكن هذه بعض الطرق التي يمكنك من خلالها تلبية المتطلبات:
أنشئ منشور مدونة أو صفحة ويب أو عنصر GitHub عام يصف العمل الذي أنجزته ويربط بالالتزامات التي أنجزتها والمستودعات التي عملت عليها. إذا كان لا يزال هناك عمل يجب القيام به في المشروع، قم بتضمين وصف لذلك العمل. يمكنك أيضًا مشاركة النقاط البارزة أو القطع الصعبة.
هذا هو الخيار الأفضل لأنه يسمح لك بتضمين الكثير من المعلومات بسهولة. يعد ذلك أمرًا جيدًا لأنه يظهر العمل الذي قمت به بوضوح، ويسهل على الآخرين استخدام مساهمتك وفهمها.
إذا كنت تستخدم GitHub، وكان كل عملك مغطى بطلب سحب واحد، فيمكنك استخدام هذا الرابط.
- تأكَّد من أنّ وصف طلب السحب مفصل.
- تأكد من أن الوصف يشير بوضوح إلى أن العمل خاص بموسم المستندات.
- إذا احتاج طلب السحب إلى مزيد من العمل بعد انتهاء "موسم المستندات"، تأكَّد من أنّ الموسم الأخير من "مستندات Google" يلتزم بهذه الحقيقة.
- تتمتع طريقة تقديم تقرير المشروع هذه بفائدة الحصول على سجل التغيير وقائمة الالتزامات وتعليقات المراجعة كل ذلك في مكان واحد.
إذا كان مستودع GitHub الخاص بك مخصّصًا لغرض واحد من أجل "موسم المستندات"، أضِف ملف README يحتوي على تفاصيل عملك.
يمكنك إنشاء مجلد عام في Google Drive وتضمين جميع التصحيحات التي أنشأتها.
أنشئ جدول بيانات عامًا باستخدام "جداول بيانات Google" واذكر جميع التزاماتك.
رابط لمشكلة واحدة في أداة تتبع المشكلات العامة، تحتوي على إشارات واضحة إلى عملك وأي شيء آخر مناسب. ينبغي أن تتبع المشكلة كل العمل الذي أنجزته. تأكَّد من أنّ المشكلة تتضمّن جميع التعهدات أو أنّه من السهل العثور على التعهدات بطريقة أخرى.
أدرِج رابطًا يؤدي إلى اختلاف موحد أو سياق بين تغييراتك. تأكد من تضمين عنوان يتضمن اسم مشروعك في مجال الكتابة الفنية ومن أنت، حتى يكون مفيدًا للآخرين.
أمثلة سيئة على كيفية وصف عملك
لا تفعل ما يلي:
- رابط إلى ملف tarball أو ملف ZIP يحتوي على رمز المصدر للمشروع بأكمله أو دليل العمل.
- الربط بالجزء العلوي من مستودع المصدر الأساسي للمشروع. على سبيل المثال، إذا كنت تعمل على cpython، فإن هذا الرابط لن يكون مفيدًا: https://github.com/python/cpython.
- أدرِج رابطًا إلى مستودع المصدر الخاص بالمشروع واستنساخه. هذا يجعل من الصعب معرفة التغييرات التي أجريتها لأن عملك يندمج مع عمل الآخرين.
- رابط إلى وصف مشروعك على موقع Season of Docs على الويب.
للمرشدين
يرجى مساعدة الكاتب التقني في إنشاء تقرير مشروع مناسب. من المهم القيام بذلك قبل إنشاء تقييمك الخاص لعمل الكاتب الفني.
يُرجى الاطّلاع على الروابط التالية:
- يجب أن يستوفي الطلب المتطلبات الموضّحة أعلاه.
- يجب أن تتضمن العينة التي تم إرسالها وصفًا للعمل المنجز والمتطلبات التي تم استيفاؤها وأسباب أي قرارات محددة تم اتخاذها.
لا تكمن فكرة Season of Docs في أن الكتّاب التقنيين يلجأون إلى الكثير من المستندات، من المهم أن يكون العمل مفيدًا لمشروع الاستضافة مفتوح المصدر.