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

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

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

آخر هفته همه چیز خوبه اما اول هفته‌ی بعد تمام موارد فراموش شدن

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

برچسب‌ها:

خدمات رایگان لیارا

۲.۵ گیگابایت فضای ذخیره‌سازی ابری رایگان

۲.۵ گیگابایت Object Storage سازگار با پروتکل S3 با دیسک‌های SSD به‌صورت رایگان دریافت کنید.

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

دیتابیس‌های MariaDB، PostgreSQL و Redis را فقط با یک کلیک و به‌صورت رایگان تهیه کنید.

سرویس DNS رایگان

به سادگی دامنه‌تان را اضافه کنید و به صورت رایگان رکورد‌های آن را مدیریت کنید.

۱۰۰ هزار تومان اعتبار اولیه

بعد از ثبت نام در لیارا مبلغ ۱۰۰ هزار تومان اعتبار هدیه دریافت می‌کنید که با توجه به ساعتی بودن هزینه سرویس‌ها، می‌توانید تمامی خدمات پولی را برای چندین هفته رایگان استفاده کنید.

ارسال ۱۰۰ ایمیل تراکنشی رایگان در هر ماه

در سرویس ایمیل لیارا شما می‌توانید تا ۱۰۰ ایمیل رایگان در هر ماه ارسال کنید و فقط برای بیش از آن هزینه پرداخت کنید. (به‌همراه دسترسی SMTP)

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

تفاوتی ندارد برای وبسایت خود از Node استفاده می‌کنید یا Laravel و Django، در لیارا می‌توانید به صورت کاملا رایگان آن را میزبانی کنید.

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

تجربه کار باliara_cloud@امروز خیلی خوب بود. یکی از سرویس هام رو منتقل کردم روش و راضیم. انقد سریع و جذاب کارم راه افتادم اصن باورم نمیشد! برعکس سرویس های PaaS دیگه با اون همه پیچیدگیشون. دمتون گرم
...

MohammadReza
liara testimonial
keikaavousi

بعد از بسته شدن @fandoghpaas و ناراحتی همه‌مون از اینکه یه سرویس خوب و صادق نمی‌تونه از پس هزینه‌ها بر بیاد، سرویسم رو منتقل کردم به پاس لیارا (https://liara.ir @liara_cloud) . تجربه راحت و خوب. تفاوت‌هایی داشت که کمی کار می‌خواست ولی تا الان کاملا راضی.

jadi
liara testimonial
jadi

یه خسته نباشید باید به تصمیمliara_cloud@بگم،
بعد از چندین روز سرکله زدن با سرویس های مشابه بالاخره تصمیم گرفتم لیارا رو امتحان کنم و باور نمیشه ۱۰ دقیقه بیشتر وقت نبرد،
دمتون گرم.

Arch
liara testimonial
EbadiDev

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

Ali Najafi
liara testimonial
me_ali_najafi

یکی از کارهای خوبی که جدیداً میکنم اینه که یه دیتابیس روی لیارا میسازم و به پروژه وصل میکنم اینطوری هم خونه و هم محل کار دیتابیس بروز رو دارم و راحت میتونم ادامه بدم کار روliara_cloud@

Navid
liara testimonial
1navid

عاشقliara_cloud@شدم درسته در حد AWS نیست ولی خب تجربه خوبی واسه پروژه های داخل ایران ارائه میده، میتونم رو CD هم اجراش کنم

Amir H Shekari
liara testimonial
vanenshi