سلام 

طبق تجربه من هر واحد جدا مسئول مستند سازی هست و درستش هم همینه (البته از نظر من)

زمانی وارد تیم دیگر میشود که ماژول ها به اون تیم وابسته باشه که باز هم قابل کنترله

سلام

مستند سازی کلا جز هدر دادن زمان و هزینه ریالی هیچ چیز دیگری ندارد.

آنچه که باید مستند شود usecase های هر business است که توسط تحلیلگر (تحلیلگران) هر پروژه صورت میگیره.

کد باید آنقدر تمیز نوشته بشه تا به راحتی بشه فهمید داره چیکار میکنه و وظیفه اش چی هست و اگه نیاز به مستند سازی عملکردش هست اون کد اشتباه است. نهایتا میشه از xml documentation خود vs استفاده کرد و بالای هر متد و کلاس شرح مختصری داد.

دلیل این موضوع این هستش که اولا آدم‌ها هیچ علاقه‌ای به خوندن مستندات ندارن و دوم اینکه سیستم‌‌های درحال توسعه به قدی تغییر نیازمندی پیدا میکنند که عملا تغییر در هر قسمتی باعث میشه مستندات قبلی کاملا بی استفاده بشن و تمام زمان و هزینه صرف شده بی فایده باشه. توسعه agile بهتون میگه برای تعاملات تیمی از diagram ها استفاده کنید و بعد از اینکه هدف و مسیر توسعه یک ماژول برای اعضای تیم مشخص شد اون دیاگرام رو پاک کنید چون بهش نیازی نیست. و صرفا usecaseها رو مستند کنید چون اونها هستند که زبان مشترک توسعه‌دهنده‌ها و مشتری‌ها (سهام‌داران) هستند.

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

برگرفته از کتاب agile principle and practices in csharp

سلام  خداوند و ما  بر ایمان مدائنی عزیز

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

مثلا تیم الف یک جوری مستند می کند که اگر مستند نمی کرد کلا بهتر بود!!!!  تیم ب نصفه و نیمه مستند می کنه و خیلی نمیشه روی مستنداتش حساب باز کرد! تیم ج بقدری عالی مستند می کنه که دهان آدم تا بناگوش باز می مونه! تیم دال تمام مستندها را به دروغ و کذب مس نویسه و وقتی که بعدا می خواهی به مستندات رجوع کنی متوجه کلی دروغ پردازی می شی!

جناب مدائنی عزیز! خودت بهتر از ما می دانی که یکی از مستندات هر پروژه باید بحث Trouble Shooting  پروژه باشه! ایرادات و خطاهای موجود تا کاربران بعدی بتوانند با مراجعه به آن، مشکلات خود را حل کنند!

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

لذا به این نتیجه رسیده ایم یک واحد جدا و مستقل از تیم های عملیاتی کار مستند سازی را انجام دهند تا ذینفع نباشند!!

اینجا دیگر مفهوم "تضاد منافع" پیش نخواهد آمد!!! سیاست گذار و استراتژیست مستند سازی و مدیریت دانش یک واحد جداست و در هر تیم یک نماینده جدا دارد!! نمیانده ی تیم موظف است داخل تیم عملیاتی اما زیر نظر واحد مستند سازی و طبق الزامات و تکالیف آن واحد اقدام به مستند سازی کند!

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

ممنون

سلام خداوند و ما بر سلمان عزیز

آقا حاشا و کذا!! و الناس لم تقولو ما لا تفعلون!

اخوی از شما بعید است!! یعنی چه که مستند سازی جز هدر دادن انرژی و پول عایدی دیگری ندارد!

آقا اصلا دور از جان شما!! همین خود من! یک پروژه را دارم در قالب یک تیم 30 نفره می نویسم! 3 سال هم روی پروزه وقت گذاشته ام!! صبح که از خانه راه می افتم به سمت محل کار یک تریلی 18 چرخ میاد می زنه به من و فاتحه مع الصلوات!  خب زحمات 3 ساله باد هوا!! ؟!؟!؟!؟!؟ بیزینسی که مستند نشده را چطور می شه از روی کلاس های انتزاعی و انتفاعی خواند و فهمید؟!!؟ نفر بعدی که می آید ادامه مسیر بدهد باید از اول دوباره کدنویسی کند؟!!؟!؟

بنا بر فرض یک جای پروژه یک ارور سنگین بود! یک ماه تمام طول کشید تا این ارور را برطرف کنیم! اگر این ارور و راه حل ان را مستند نکنیم توی پروژه های بعدی اگر آن ارور بوجود آمد باز باید یک ماه تمام وقت بگذاریم!؟!؟ حتما که قرار نیست در پروژه ی بعدی هم من و شما حضور داشته باشیم که! منافع سازمانی کجا می رود پس؟!؟!شاید فردا یک پروژه ی دیگر در سازمان تعریف شود و مدیر پروژه من و شما نباشیم و فرد دیگری باشد!! او نباید از دانش تولید شده قبلی که با صرف منابع سازمالن بودجود آمده بهره برداری کند؟!؟!!؟

اتفاقا یا این عمر ناقابل و این تجربه ی کم خود به این نتیجه رسیده ام یکی از دلایل شکست پروژه ها، همین عدم مستند سازی دقیق و علمی است!

یادش بخیر! سال 92 و 93 در یکی از کشورهای همسایه مشغول بکار بودم! مدیر پروژه یک فردی بود حدود 35 ساله از یکی از کشورهای امریکای جنوبی! از وی خیلی چیزها یاد گرفتم در عالم برنامه نویسی!  واقعا نحوه تولید نرم افزار آنها با تولید ما زمین تا آسمان که نه! به اندازه میلیاردها سال نوری تفاوت داشت!  یکی از چیزهایی که ایشان به شدت اصرار و دقت داشت همین مستند سازی با درج جزییات بود! مثلا یک متغیر را از نوع int  می گرفتی می گفت توی کاغذ و مستندات پروژه بنویس که چرا مثلا double  نگرفتی!

شما نوشته ای همین XML Documentation  کافیست!!!!! برادر مستندات یک پروژه که فقط کدهایش نیست!! پس تیم پشتیبانی نرم افزار از کجا مکشلات را بفهمد؟!؟!

شما فردا برای سرویس های درون پروژه ات باید کلی از تنظیمات IIS  را تغییر بدهی!  شما همیشه که پروژه هایت 100 تا کاربر که ندارد!! امروز یک نرم افزار شبکه بانکی روزی حدود یک میلیون تراکنش انجام میدهد! نیاز به  Load Balancer   خواهی داشت! فردا اگر من سرمو گذاشتم زمین و جان به جان آفرین تسلیم کردم کل شبکه بانکی کشور مثلا باید مختل شود؟!؟!!؟ نمی شود که اینجوری!

مخلص کلام!

در اصل مستندسازی هیچ شک و شبهه ای نیست! مشکل در نحوه ی مستندسازی است!