چطور باید برای یک پروژه دفترچه مشخصات فنی تهیه کرد؟
نویسنده: هادی مزارعی
تاریخ: ۱۴۰۳/۰۵/۱۲ ۱۶:۰۳
آدرس: www.dntips.ir
عنوان:
نویسنده: هادی مزارعی
تاریخ: ۱۴۰۳/۰۵/۱۲ ۱۶:۰۳
آدرس: www.dntips.ir
نویسنده: هادی مزارعی
تاریخ: ۱۴۰۳/۰۵/۱۲ ۱۶:۰۳
آدرس: www.dntips.ir
سلام
نمیدونم عبارات و اصطلاحاتی که بکار میبرم درسته یا خیر.
آیا برای تهیه دفتر مشخصات فنی یک پروژه نرم افزاری الگو و ساختار استانداردی وجود دارد؟ در واقع قصد دارم تمامی جزئیات ساختاری پروژه را مستند کنم تا بشه بر مبنای اون دفترچه، برنامه را از حیث پیاده سازی تجزیه تحلیل کرد.
تشکر
مطالب مشابه
-
اشتراک‌هاSymfony AI v0.2.0 Released: Feature Breakdown and Practical Guideاشتراک‌هاDev Leader Podcast – Is Developer Relations Right for You? An Honest Breakdown With Fred Harperمطالببررسی داده کاوی و OLAPمطالبDomain-Driven Design (DDD)؛ بخش هشتم: الگوهای Repository و Specificationمطالبخلاصه اشتراک‌های روز چهار شنبه 4 آبان 1390مطالبخلاصه اشتراک‌های روز جمعه 6 آبان 1390مطالبچرا توسعه چابک (Agile Development)؟نظرات مطالباستخراج متن از فایل‌های PDF توسط iTextSharpنظرات نظرسنجی‌هابرای نگهداری لیست کارهای روزمره بیشتر از ابزارهای دیجیتال(Excel, Evernote, ..) استفاده میکنید و یا فیزیکی(دفترچه، تخته و...)؟نظرسنجی‌هاچه عواملی باعث میشود که شما از ادامه یا تکمیل پروژه دلسرد شوید؟
نظرات
- امین مصباحی در ۱۴۰۳/۰۵/۱۲ ۱۶:۳۸
استاندارد خیر. ولی best practice هایی وجود داره.
و خیلی خیلی بستگی به سایزسازمان و تیم، ساختار تیم و روش توسعه، و عمق مستنداتی که تولید میکنید داره، مثال: گاهی یک تیم بزرگ تصمیم می‌گیره از ابزار wiki موجود در Gitlab, GitHub, Azure DevOps استفاده کنه (همون‌جایی که سورس کد قرار داره، ولی در بخش ویکی) یا در کانفلوئنس (اگر داشته باشن)
گاهی در فایل README.md در root پروژه به شکل قراردادی مشخصات ذکر می‌شه.
گاهی فایل‌های markdown در پوشه docs در سورس‌کد
گاهی شما نیاز به معرفی REST API دارید که OpenAPI Spec کمک میکنه
گاهی دیاگرام هم نیاز دارید برای یک سیستم بزرگ‌تر
گاهی فقط وابستگی‌ها مثل پکیج‌ها براتون مهمه، که فایل .packages.props کمک میاد
تجربه شخصی من، نسبت به هر تیم و شرکتی متناسب با همون تصمیم گرفتم (از فایل README.MD تا مدخل در ویکی که بعد از مدتی به چندصد صفحه تبدیل شده که چندین نفر به تدریج کاملش کردند)
- سیروان عفیفی در ۱۴۰۳/۰۵/۱۲ ۱۸:۴۹
مستندات فنی که اصطلاحاً به صورت high-level هستند و خیلی به صورت مداوم به‌روز نمیشن رو شاید بهتر باشه خارج از سورس‌کد ذخیره کرد. روالی که من توی تیم‌ها میبینم اینطور بوده که یک ساختار این مدلی داشتن:
- Archives
- Technical
- ADRs
- Architetures
- QA
- UX Researches
- Meetings
- Releases
برای مستندات فنی‌تر هم همونطور که اشاره کردید توی پوشه docs/ به صورت markdown قرار میگیرن؛ نکته مهمی که دسترسی رو برای همه ساده‌تر میکنه داشتن یک فایل ایندکس (markdown) هست.
در نهایت میتونید همه رو داخل همون پوشه docs/ قرار بدید و به صورت قابل دیپلوی در دسترس بقیه اعضای تیم قرار بدید (میتونه بخشی از فرآیند CI/CD باشه مثلاً به محض مرج شدن یک فیچر در برنچ اصلی محتویات پوشه docs/ هم دیپلوی بشه) ابزارهای زیادی هم برای اینکار استفاده میشن مثلاً میتونید از Docusaurus برای اینکار استفاده کنید:
- سالار ربال در ۱۴۰۳/۰۵/۱۲ ۲۱:۳۴
من تجربه استفاده ترکیبی از C4 Model برای نمایش بصری معماری سیستم در چندین سطح مختلف را به همراه قالب خوش فرم MADR (Markdown Any Decision Records) را داشتم. در نسخه های قبلی MADR برای مستند سازی تصمیمات معماری استفاده می شد که بعد از نسخه ۳ برای ثبت و ضبط تمام تصمیمات تاثیرگذار در طراحی سیستم می توان استفاده کرد. این موارد در کنار مستندات OpenAPI Spec که امین جان عنوان کردند، در کنار سورس کد برنامه در پوشه docs نگهداری می شوند.
علاوه بر موارد مطرح شده، استفاده از Gherkin برای نوشتن سناریوهای تست نیز می تواند به عنوان ابزار خوبی برای مستندسازی رفتار سیستم باشد؛ به طوری که با زبان مختص دامین مورد نظر رفتار سیستم را شرح داده است.