چگونه مستندات مناسبی برای برنامه‌هایمان بنویسیم؟

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

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

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

۱) با یادداشت‌های دقیق شروع کنید

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

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

• دستورهایی که در terminal وارد می‌کنید.
• دلیل انتخاب یک method خاص در مواردی که انتخاب‌های مختلفی پیش روی شما است.
• منابعی که توانسته‌اید از آن‌ها ایده بگیرید.
• ترتیب انجام کارها.

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

۲) تصمیم‌های خود را کاملا توضیح دهید

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

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

• چالش‌هایی که با آن‌ها روبرو شده‌اید و چگونگی غلبه بر آن‌ها
• تصمیم‌های اتخاذ شده برای انتخاب نوعی معماری که اهداف پروژه شما را انتقال می‌دهند

توضیح دهید تا اکثر سوال‌هایی که ممکن است پرسیده شود را از قبل پاسخ داده باشید.

۳) پیش‌نیازهای ساده را حتما ذکر کنید

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

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

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

۴) همه‌ی موارد را مستند کنید

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

منبع: https://www.freecodecamp.org/news/how-to-write-good-documentation