مخصوص ناشنوایان
چطور مستندات (داکیومنت) خوبی بنویسیم
ایمان مدائنی

در این مقاله، ما دلیل فراموش کردن نحوه کار پروژه را در سه مرحله توضیح می‌دهیم. در تیم‌های برنامه‌نویسی همیشه باید همه چیز مستند شود. مستندات همیشه باید در کنار کد قرار بگیرند.

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

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

در اینجا سه مرحله متصل به هم وجود دارد که می‌توانید برای نوشتن داکیومنت خوب استفاده کنید، قبل از اینکه خیلی دیر شود.

1. با یادداشت‌های دقیق شروع کنید

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

یک داکیومنت را در کنار کد خود باز نگه دارید و مواردی مانند دستورات، تصمیمات و منابع مورد استفاده را یادداشت کنید. این امر می‌تواند شامل موارد زیر باشد:

چرا متد خاصی را به جای متد دیگر انتخاب کرده‌اید

لینک‌هایی که برای کمک گرفتن از آن‌ها بازدید کرده‌اید

ترتیب انجام کارها

در این مرحله نگران جملات کامل نباشید. فقط مطمئن شوید که متن، قطعه کدهای مربوطه و URLهای سودمند را به طور دقیق گرفته‌اید.

2. تصمیمات را به صورت گسترده‌تر توضیح دهید

زمان ایده‌آل برای انجام این مرحله زمانی است که کد نمی‌زنید و در حال استراحت هستید، اما قبل از اینکه به طور کامل کار خود را ترک کنید و مثلا برای صرف ناهار بروید، این کار را انجام دهید.

شما می‌خواهید مطمئن شوید که محتوا، ایده‌ها و تصمیم‌گیری‌ها، وقتی آن‌ها را برای خود توضیح می‌دهید، همه در ذهن شما تازه هستند.

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

من معمولا این کار را انجام می‌دهم، اما این بار تصمیم گرفتم کاری متفاوت انجام دهم زیرا...

چالش‌هایی که با آن رو به رو شده‌اید و نحوه غلبه بر آن‌ها

تصمیمات معماری که اهداف پروژه شما را پشتیبانی می‌کند

به نکات اصلی پایند باشید. نوشتن‌های طولانی همیشه به معنای خوب بودن نیست. فقط از جملات کامل استفاده کنید، و طوری بنویسید که گویا پروژه خود را برای یک همکار توضیح می‌دهید. به هر حال شما در حال توضیح دادن برای آینده خود هستید.

3. از دانش مورد نیاز غافل نشوید

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

برای نوشتن یا حداقل لینک شدن به دانش موردنیاز، دقت بیشتری کنید، به خصوص اگر مرتبا از زبان‌ها و ابزارهای مختلف استفاده می‌کنید. حتی کارهای کوچک مانند گذاشتن لینک در مستندات API می‌تواند در آینده از ساعت‌ها جستجو کردن شما جلوگیری کرده و در وقت‌تان صرفه‌جویی کند.

لینک به READMEs، مراحل نصب، و سایر موارد پشتیبانی مربوطه را بنویسید یا لینک کنید. اقدامات command-line که مرتبا انجام می‌دهید را طوری برای خود مرتب یا حتی اتومات کنید که هر بار که به پروژه برمی‌گردید، مجبور به انجام کارهای معمول نباشید.

شما به راحتی می‌توانید جزئیات پشتیبانی را حتی پس از استراحت کوتاهی از پروژه خود فراموش کنید. پس هر بار که هر چیزی را سودمند یافتید آن را یادداشت کنید.

همه موارد را مستند کنید

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

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

نظرات کاربران در رابطه با این دوره

جهت ثبت نظر باید در سایت عضو شوید و یا وارد سایت شده باشید .
logo-samandehi