از پیگیری شما برای بهبود و توسعه مستندات کداستار سپاس‌گزاریم و امیدواریم با کمک شما این مستندات برای استفاده آیندگان غنی‌تر و بهتر شود.
مشارکت شما می‌تواند به بهتر شدن مستندات فعلی کمک کند، خوشحال می‌شویم در این زمینه‌ها Pull Request ایجاد کنید.
-
اضافه‌کردن لینک‌ها و منابع بهتر به مستند شامل:
- لینک وبسایت
- ویدیو
- تصویر
-
اضافه‌کردن توضیحاتی که به گویایی و قابل فهم‌تر شدن مستند برای کارآموزان کمک کند
-
اضافه کردن ابزار‌ها، تکنیک‌ها و کتابخانه‌های جدید در مستندات
-
اصلاحات نگارشی و املایی
بعد از ایجاد PR به نگارنده مستند پیام دهید و لینک PR را بفرستید تا در اسرع وقت بهبود‌های شما در دسترس همه قرار گیرد، دقت کنید حتماً قسمت نکاتی در مورد لحن و نگارش را که در پایان این مستند آمده است رعایت کرده باشید.
در صورتی که جزء منتور‌های اصلی آکادمی هستید و قصد دارید مستندات یک فاز را تدوین کنید به نکات زیر توجه کنید:
-
به ازای هر فاز یک پوشه جداگانه بسازید و همه فایل‌های مرتبط را در آن پوشه قرار دهید.
-
هر فاز شامل دو فایل اصلی است:
-
مستند اصلی با نام استاندارد مشابه سایر مستندات، مثلاً: Phase05-Web.md
-
مستند ایشو تمپلیت که شامل چک‌لیست کار‌های کارآموز است (به دلیل بهم ریختن نمایش چک باکس‌ها در این مستند از زبان انگلیسی استفاده می‌کنیم اما کارآموزان می‌توانند به هر دو زبان فارسی یا انگلیسی، به پرسش‌ها پاسخ دهند.) با نام استاندارد: issue-template-Phase05.md
-
سایر فایل‌ها مثل تصاویر و فایل‌های استفاده شده در مستند اصلی در پوشه مربوط به فاز قرار می‌گیرند.
-
-
تلاش کنید منابع استفاده شده در مستندات ساده و گویا باشد و حتماً قبل از ارجاع به یک سایت یا ویدیو خودتان یک بار کل توضیحات آن را بخوانید (یا کل ویدیو را ببینید) و از مفید بودن و صحت آن مطمئن شوید.
-
توضیحات فارسی خود را به صورت کاملاً گویا و روان بنویسید و حداقل دو بار مستند را بخوانید تا از قابل فهم بودن جملات و همچنین درستی لحن و نگارش مطمئن شوید، دقت کنید مستندات شما را ده‌ها نفر مطالعه می‌کنند و هر چه قابل فهم‌تر باشد صرفه‌جویی بیشتری در زمان دیگران می‌شود و راندمان کارآموزی بالاتر می‌رود.
-
تناسب میان مستند اصلی و مستند ایشو تمپلیت مهم است، حتماً ترتیب چک‌لیست با قسمت‌بندی مستند تطابق داشته‌باشد.
-
اسامی فایل‌ها و پوشه‌بندی آن‌ها را طوری انتخاب کنید که تا جای ممکن در آینده نیاز به rename نباشد زیرا با rename لینک‌های گذشته به آن مستند نامعتبر می‌شود و کاربران با خطای 404 مواجه می‌شوند. معمولاً می‌توان لینک‌های داخل repo را اصلاح کرد اما بسیاری از افراد لینک به این مستند را در پیام رسان‌ها و ... به اشتراک گذاشته‌اند که اصلاح آن غیرممکن است پس تا جای ممکن از rename دوری کنید.
-
ارجاع به تصاویر و فایل‌های داخلی حتماً به صورت relative باشد تا در سایر branch ها از کار نیفتند.
-
در مستندات از فارسی محاوره‌ای استفاده نکنید. مثال:
بخونین=> بخوانید
-
از بکارگیری فعل‌های جمله به صورت اول شخص مفرد و دوم شخص مفرد دوری کنید. مثال:
-
پیشنهاد می‌کنم اول لینک زیر را بخوانی=> پیشنهاد می‌کنیم اول لینک زیر را بخوانید -
در شرایط خاصی مثل مستندات HR و ایشوی Onboarding استفاده از لحن خودمانی‌تر و دوم شخص مفرد اشکالی ندارد.
-
-
حتماً نکات املایی و دستور زبان فارسی را در نگارش و بازبینی مستندات رعایت کنید.
-
از عبارت‌های پیچیده و همچنین کلمات فوق العاده رسمی دوری کنید. مثال:
-
لذا=> بنابراین ابتدا=> اولایجاد گردید=> درست شد
-
-
در مستندات فنی از افراط در فارسی نویسی پرهیز کنید به خصوص جایی که باعث سختی فهم شود، مثلاً در مستندات مربوط به وب بهتر است بین سه کلمه ریدایرکت و redirect و هدایت از کلمه redirect استفاده کنید.
-
روی رعایت راست‌چین و چپ‌چین در مستندات فارسی حساس باشید به گونه‌ای که خواننده مستند برای خواندن اذیت نشود.
-
علائم نگارشی مانند ویرگول و نقطه را در جایگاه مناسب به کار ببرید.