سلام
نمیدونم عبارات و اصطلاحاتی که بکار میبرم درسته یا خیر.
آیا برای تهیه دفتر مشخصات فنی یک پروژه نرم افزاری الگو و ساختار استانداردی وجود دارد؟ در واقع قصد دارم تمامی جزئیات ساختاری پروژه را مستند کنم تا بشه بر مبنای اون دفترچه، برنامه را از حیث پیاده سازی تجزیه تحلیل کرد.
تشکر
استاندارد خیر. ولی best practice هایی وجود داره.
و خیلی خیلی بستگی به سایزسازمان و تیم، ساختار تیم و روش توسعه، و عمق مستنداتی که تولید میکنید داره، مثال: گاهی یک تیم بزرگ تصمیم می‌گیره از ابزار wiki موجود در Gitlab, GitHub, Azure DevOps استفاده کنه (همون‌جایی که سورس کد قرار داره، ولی در بخش ویکی) یا در کانفلوئنس (اگر داشته باشن)
گاهی در فایل README.md در root پروژه به شکل قراردادی مشخصات ذکر می‌شه.
گاهی فایل‌های markdown در پوشه docs در سورس‌کد
گاهی شما نیاز به معرفی REST API دارید که OpenAPI Spec کمک میکنه
گاهی دیاگرام هم نیاز دارید برای یک سیستم بزرگ‌تر
گاهی فقط وابستگی‌ها مثل پکیج‌ها براتون مهمه، که فایل .packages.props کمک میاد
تجربه شخصی من، نسبت به هر تیم و شرکتی متناسب با همون تصمیم گرفتم (از فایل README.MD تا مدخل در ویکی که بعد از مدتی به چندصد صفحه تبدیل شده که چندین نفر به تدریج کاملش کردند)
مستندات فنی که اصطلاحاً به صورت high-level هستند و خیلی به صورت مداوم به‌روز نمیشن رو شاید بهتر باشه خارج از سورس‌کد ذخیره کرد. روالی که من توی تیم‌ها میبینم اینطور بوده که یک ساختار این مدلی داشتن:
برای مستندات فنی‌تر هم همونطور که اشاره کردید توی پوشه docs/ به صورت markdown قرار میگیرن؛ نکته مهمی که دسترسی رو برای همه ساده‌تر میکنه داشتن یک فایل ایندکس (markdown) هست.
در نهایت میتونید همه رو داخل همون پوشه docs/ قرار بدید و به صورت قابل دیپلوی در دسترس بقیه اعضای تیم قرار بدید (میتونه بخشی از فرآیند CI/CD باشه مثلاً به محض مرج شدن یک فیچر در برنچ اصلی محتویات پوشه docs/ هم دیپلوی بشه) ابزارهای زیادی هم برای اینکار استفاده میشن مثلاً میتونید از Docusaurus برای اینکار استفاده کنید:
من تجربه استفاده ترکیبی از C4 Model برای نمایش بصری معماری سیستم در چندین سطح مختلف را به همراه قالب خوش فرم MADR (Markdown Any Decision Records) را داشتم. در نسخه های قبلی MADR برای مستند سازی تصمیمات معماری استفاده می شد که بعد از نسخه ۳ برای ثبت و ضبط تمام تصمیمات تاثیرگذار در طراحی سیستم می توان استفاده کرد. این موارد در کنار مستندات OpenAPI Spec که امین جان عنوان کردند، در کنار سورس کد برنامه در پوشه docs نگهداری می شوند.
علاوه بر موارد مطرح شده، استفاده از Gherkin برای نوشتن سناریوهای تست نیز می تواند به عنوان ابزار خوبی برای مستندسازی رفتار سیستم باشد؛ به طوری که با زبان مختص دامین مورد نظر رفتار سیستم را شرح داده است.
