محمد کشاورز

برنامه نویس ، توسعه دهنده – Mokech

چطور داکیومنت بنویسیم؟

بدون دیدگاه

یکی از کارهایی که کمتر کسی حوصله انجام دادنش رو داره همین داکیومنت نویسیه. بیان و نوشتن اینکه چه کاری انجام دادی در ظاهر کار خسته کننده و شاید بی فایده‌ای به نظر بیاد چون با خودمون میگیم که: “خب نفر بدی که میاد برنامه نویسه! حتما یه نگاه به کدهای من بندازه میدونه چی نوشتم”

اما این جمله درست نیست چون بعضی تصمیم‌ها تو ذهن ما یا به صورت شفاهی بین تیم انجام شده و ما نتیجه این تصمیم‌ها رو توی کد اجرا می کنیم و میبینیم.

چرا مستندسازی یا داکیومنت نویسی لازم است؟

به این فکر کنید که رفتید یه شرکت جدید و اولین روز کاریتون هست و صدای نوتیفیکشن برنامه مدیریت پروژه میاد که خبر از یه تسک میده که به شما محول شده.
شرح تسک رو میخونی و کار رو شروع میکنی.بعد از چند ساعت که کار انجام شد و خودت هم یه اسموک تست ساده زدی با خوشحالی میگی که تسک دان شد و بره برای تست و استیج و این ماجراها. کد میره برای ریویوو و کسی که داره ریویوو میکنه متوجه میشه که شما چندتا متد رو override کردی و کلا با شیوه خودت کدنویسی کردی و هرچی دستت اومده ریختی تو کدها! از طرفی هم یه سری شیرین کاری‌هایی توی کد انجام دادی (!) که نمیشه فرستاد روی پروداکت، اینجاست که نیاز به یک داکیومنت مناسب و درست برای تیم احساس میشه.

وقتی مشغول خوندن کدهای پروژه هستی همچین سوال‌هایی برات به وجود میاد:

  • چرا اینجا این تصمیم رو گرفتن؟
  • برای چی از فلان کتابخونه استفاده نشده؟اون که خیلی سریعتره
  • چرا تو بخش‌های مختلف به روش‌های متفاوتی کد نوشته شده؟

داکیومنت خوب باید بتونه به همچین سوال‌هایی جواب بده که فرد تازه وارد تو دوره Onboarding بتونه کارش رو با کمترین مزاحمت برای بقیه افراد پیش ببره.
اینطوری توی زمان بقیه افراد تیم صرفه جویی میشه و سوالاتی که متداول هستن جوابش توی داکیومنت وجود داره و وابستگی افراد به همدیگه کمتر میشه.

در داکیومنت چه چیزی بنویسیم؟

اول ببینیم قراره این مستند نوشته شده به کار چه کسی یا چه زمانی به کار بیاد.

  1. عضو جدید تیم
  2. ایجاد تغییر در قسمتی که خیلی وقته روش کار نکردیم

تو هر دو حالت افراد اطلاع کاملی از جزئیات اون بخشی که قراره تغییراتی ایجاد کنن ندارن، یا فراموش کردن یا آشنایی با اون قسمت ندارن.

پس این داکیومنتی که نوشته شده باید بتونه پرسش‌ها و ابهام‌هایی که براشون به وجود اومده رو جواب بده.

مخاطب این داکیومنت را بشناسید

  • برای چه کسی داکیومنت مینویسیم؟
  • جونیور هست یا سینیور؟
  • مرزهای دامین اطلاعات تا کجاست؟ به جز اعضای تیم، فرد یا افراد دیگه‌ای از این پروژه استفاده میکنن؟

با مشخص شدن گروه مخاطب‌های داکیومنت، موقع نوشتن میدونیم که باید چه نکاتی نوشته بشه و چقدرلازم هست که همراه با جزئیات نوشته بشه یا به صورت کلی و ضمنی به موضوع موردنظر اشاره بشه.

هر چیزی که داکیومنتش وجود داره نباید نوشته بشه! مثل فریمورک و کتابخونه و پکیج و …

هر چیزی که فرد میتونه با سرچ و گوگل کردن متوجه بشه نیازی به داکیومنت کردن نداره.مثلا فلان متد چطور کار میکنه نیازی به نوشتن نداره

مگر اینکه اون متد توی helper functions نوشته شده باشه و خیلی مشخص نباشه که چه کاری انجام میده و یا استفاده خیلی خاصی براش در نظر گرفته شده و لازم است که تو استفاده و یا تغییرش، دقت و با بقیه هماهنگی انجام بشه.

پایان بخش اول



دیدگاهتان را بنویسید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *