فاز فعلی:
برنامه Season of Docs 2019 در 6 مارس 2020 به پایان رسید. جدول زمانی را ببینید.
این صفحه حاوی دستورالعمل هایی برای نویسندگان فنی در مورد نحوه ایجاد گزارش پروژه خود پس از اتمام کار خود برای فصل اسناد امسال است.
ارائه گزارش پروژه شما
وقتی مرحله نهایی‌سازی پروژه باز می‌شود، می‌توانید با تکمیل فرمی که در بخش نهایی‌سازی پروژه راهنمای نگارش فنی در دسترس است، گزارش پروژه خود را ارسال کنید.
اطلاعاتی که باید در گزارش پروژه گنجانده شود
این بخش نوع اطلاعاتی را که می توانید در گزارش پروژه خود ارائه دهید، توضیح می دهد. فرم گزارش پروژه شامل فیلدهای متن آزاد و همچنین سوالات چند گزینه ای خواهد بود.
به کار خود لینک دهید
پیوندی ارائه دهید که به شرح کاری که انجام داده اید اشاره می کند.
پیوند باید به سندی اشاره کند که حاوی شرح کوتاهی از کار انجام شده، اسنادی که پروژه منبع باز در مخزن آن ادغام شده است، خلاصه ای از وضعیت فعلی پروژه و فهرستی از چالش ها و آموخته ها باشد.
پیوند در نتایج فصل اسناد منتشر شده در وب سایت ظاهر می شود. نتایج منتشر شده نشان دهنده کاری است که در طول برنامه انجام داده اید. نتایج منتشر شده همچنین راهی عالی برای شما است که به عنوان بخشی از رزومه خود به کار خود مراجعه کنید.
شما باید پیوند خود را با مربی خود به اشتراک بگذارید و قبل از ارسال گزارش پروژه خود، درخواست بررسی کنید.
الزامات گزارش پروژه شما
الزامات زیر را در نظر بگیرید:
- محتوای پیوند شده باید شناسایی کاری را که در طول فصل اسناد تکمیل کرده‌اید، یعنی تغییراتی که ایجاد کرده‌اید یا اسناد جدیدی که نوشته‌اید، آسان کند.
- کار باید در یک مکان ثابت باشد. بعد از ارسال نمی توانید URL را تغییر دهید.
شخص دیگری باید بتواند از محتوا در هدف پیوند استفاده کند (یا به آن ارجاع داده شود تا بر روی کار شما بسازد.
- اگر کار شما 100% کامل است، افراد دیگر باید بتوانند از آن استفاده کنند.
- اگر کار شما 100% کامل نشده است، باید مشخص باشد که چه کاری باقی مانده است.
نمونه های خوبی از نحوه توصیف کار خود
شما مجبور نیستید همه (یا هیچ کدام) از این کارها را انجام دهید، اما اینها چند راه هستند که می توانید شرایط را برآورده کنید:
یک پست وبلاگ یا صفحه وب یا کلیات GitHub عمومی ایجاد کنید که کارهایی را که انجام داده اید توصیف می کند و به تعهداتی که انجام داده اید و مخازنی که روی آنها کار کرده اید پیوند می دهد. اگر هنوز کاری برای انجام پروژه وجود دارد، شرح آن کار را درج کنید. همچنین می توانید نکات برجسته یا قطعات چالش برانگیز را به اشتراک بگذارید.
این بهترین گزینه است زیرا به شما امکان می دهد اطلاعات زیادی را به راحتی درج کنید. این خوب است زیرا کار شما را به وضوح نشان می دهد و استفاده و درک مشارکت شما را برای دیگران آسان می کند.
اگر از GitHub استفاده می کنید و تمام کارهای شما با یک درخواست کشش پوشش داده می شود، می توانید از آن پیوند استفاده کنید.
- اطمینان حاصل کنید که توضیحات درخواست کشش دقیق است.
- اطمینان حاصل کنید که توضیحات به وضوح به این نکته اشاره می‌کند که کار مربوط به Season of Docs است.
- اگر پس از پایان Season of Docs درخواست pull به کار بیشتری نیاز دارد، مطمئن شوید که آخرین Season of Docs commit به این واقعیت توجه داشته باشد.
- این روش ارائه گزارش پروژه از مزایای داشتن گزارش تغییرات، لیستی از تعهدات و نظرات بررسی همه در یک مکان برخوردار است.
اگر مخزن GitHub شما برای Season of Docs تک منظوره است، یک فایل README حاوی جزئیات کار خود اضافه کنید.
یک پوشه عمومی در Google Drive ایجاد کنید و همه وصله‌هایی که ایجاد کرده‌اید را در آن قرار دهید.
با Google Sheets یک صفحه گسترده عمومی ایجاد کنید و تمام تعهدات خود را فهرست کنید.
پیوند به یک شماره واحد در یک ردیاب شماره عمومی، که حاوی ارجاعات واضح به کار شما و هر چیز مناسب دیگری است. موضوع باید تمام کارهایی را که انجام داده اید ردیابی کند. اطمینان حاصل کنید که مشکل همه commit ها را فهرست می کند یا اینکه یافتن commit ها به روش دیگری آسان است.
به یک تفاوت یکپارچه یا زمینه تغییرات خود پیوند دهید. حتماً یک هدر اضافه کنید که شامل نام پروژه نگارش فنی شما و شخصیت شما باشد، بنابراین برای دیگران مفید است.
مثال های بدی از نحوه توصیف کارتان
این کارها را انجام ندهید:
- پیوند به تاربال یا فایل فشرده حاوی کد منبع کل پروژه یا دایرکتوری کاری شما.
- به بالای مخزن منبع اصلی پروژه پیوند دهید. برای مثال، اگر روی cpython کار می‌کنید، این پیوند مفید نیست: https://github.com/python/cpython .
- به کلون خود از مخزن منبع پروژه پیوند دهید. این باعث می شود که دیدن تغییرات شما دشوار باشد زیرا کار شما با کارهای دیگران مخلوط شده است.
- به شرح پروژه خود در وب سایت Season of Docs پیوند دهید.
برای مربیان
لطفاً به نویسنده فنی خود کمک کنید تا یک گزارش پروژه مناسب ایجاد کند. مهم است که این کار را قبل از ایجاد ارزیابی خود از کار نویسنده فنی انجام دهید.
موارد زیر را بررسی کنید:
- ارسال باید دارای شرایط ذکر شده در بالا باشد.
- ارسال باید شامل شرح کار انجام شده، الزامات برآورده شده و دلایل تصمیمات خاص باشد.
ایده Season of Docs این نیست که نویسندگان فنی مستندات زیادی تهیه کنند. مهم است که کار به طور بالقوه برای پروژه منبع باز میزبانی مفید باشد.