سلام، هابر! نام من لشا است، من یک تحلیلگر سیستم برای یکی از تیم های محصولات آلفا بانک هستم. اکنون در حال توسعه یک بانک آنلاین جدید برای اشخاص حقوقی و کارآفرینان فردی هستم.
و وقتی شما یک تحلیلگر هستید، به خصوص در چنین کانالی، نمی توانید بدون مستندات و کار با آن به جایی برسید. و مستندسازی چیزی است که همیشه سوالات زیادی را ایجاد می کند. چرا برنامه وب توضیح داده نشده است؟ چرا مشخصات نشان می دهد که سرویس چگونه باید کار کند، اما اصلاً اینطور کار نمی کند؟ چرا فقط دو نفر که یکی از آنها نوشته است می توانند مشخصات را بفهمند؟
با این حال، اسناد را نمی توان به دلایل واضح نادیده گرفت. و برای سهولت در زندگی، تصمیم گرفتیم کیفیت اسناد را ارزیابی کنیم. اینکه دقیقاً چگونه این کار را انجام دادیم و به چه نتیجه‌ای رسیدیم در زیر برش است.
کیفیت مستندات
برای اینکه "بانک اینترنتی جدید" را چندین ده بار در متن تکرار نکنم، NIB خواهم نوشت. اکنون بیش از دوازده تیم داریم که روی توسعه NIB برای کارآفرینان و اشخاص حقوقی کار می کنند. علاوه بر این، هر یک از آنها یا مستندات خود را برای یک سرویس یا برنامه وب جدید از ابتدا ایجاد می کند یا تغییراتی را در مورد فعلی ایجاد می کند. با این رویکرد، آیا اصولا مستندات می توانند کیفیت بالایی داشته باشند؟
و برای تعیین کیفیت مستندات، سه ویژگی اصلی را شناسایی کرده ایم.
- باید کامل باشه این به نظر کاپیتان مانند است، اما توجه به آن مهم است. باید تمام عناصر راه حل اجرا شده را با جزئیات شرح دهد.
- باید مرتبط باشد. یعنی با اجرای فعلی خود راه حل مطابقت دارد.
- باید قابل درک باشد. به طوری که شخصی که از آن استفاده می کند متوجه می شود که چگونه راه حل پیاده سازی شده است.
به طور خلاصه - مستندات کامل، به روز و قابل فهم.
Опрос
برای ارزیابی کیفیت مستندات، تصمیم گرفتیم با کسانی که مستقیماً با آن کار می کنند مصاحبه کنیم: تحلیلگران NIB. از پاسخ دهندگان خواسته شد تا 10 عبارت را طبق طرح "در مقیاس 1 تا 5 (کاملاً مخالف - کاملاً موافقم) ارزیابی کنند.
اظهارات منعکس کننده ویژگی های مستندات کیفی و نظر گردآورندگان نظرسنجی در مورد اسناد NIB بود.
- مستندات برنامه های NIB به روز و کاملاً با اجرای آنها سازگار است.
- اجرای برنامه های NIB به طور کامل مستند شده است.
- اسناد برای برنامه های NIB فقط برای پشتیبانی عملکردی مورد نیاز است.
- مستندات برنامه های NIB در زمان ارائه آنها برای پشتیبانی عملکردی موجود است.
- توسعه دهندگان برنامه NIB از مستندات برای درک آنچه که باید پیاده سازی کنند استفاده می کنند.
- مستندات کافی برای برنامه های NIB وجود دارد تا بفهمند چگونه پیاده سازی می شوند.
- من اسناد پروژه های NIB را در صورت نهایی شدن (توسط تیم من) به سرعت به روز می کنم.
- توسعه دهندگان برنامه NIB اسناد را بررسی می کنند.
- من درک روشنی از نحوه تهیه اسناد برای پروژه های NIB دارم.
- می‌دانم چه زمانی باید اسناد را برای پروژه‌های NIB بنویسم/به‌روزرسانی کنم.
واضح است که پاسخ دادن به "از 1 تا 5" ممکن است جزئیات لازم را نشان ندهد، بنابراین یک فرد می تواند در مورد هر مورد نظر بگذارد.
ما همه این کارها را از طریق شرکت Slack انجام دادیم - ما به سادگی یک دعوت نامه برای تحلیلگران سیستم ارسال کردیم تا نظرسنجی کنند. 15 تحلیلگر (9 نفر از مسکو و 6 نفر از سن پترزبورگ) حضور داشتند. پس از تکمیل نظرسنجی، برای هر یک از 10 عبارت یک نمره متوسط ایجاد کردیم که سپس آن را استاندارد کردیم.
این چیزی است که اتفاق افتاده است.
این نظرسنجی نشان داد که اگرچه تحلیلگران تمایل دارند بر این باورند که اجرای برنامه‌های NIB کاملاً مستند است، اما توافق صریح ندارند (0.2). به عنوان مثال مشخص، آنها اشاره کردند که تعدادی از پایگاه‌های داده و صف‌های موجود از راه‌حل‌های موجود تحت پوشش مستندات قرار نگرفتند. توسعه دهنده می تواند به تحلیلگر بگوید که همه چیز مستند نیست. اما این تز که توسعه دهندگان اسناد را بررسی می کنند نیز پشتیبانی واضحی دریافت نکرد (0.33). یعنی خطر شرح ناقص راه حل های اجرا شده باقی می ماند.
ارتباط آسان تر است - اگرچه باز هم توافق روشنی وجود ندارد (0,13)، تحلیلگران هنوز تمایل دارند که مستندات را مرتبط در نظر بگیرند. نظرات به ما این امکان را می دهد که بفهمیم مشکلات مربوط به ارتباط بیشتر در جلو هستند تا وسط. با این حال، آنها چیزی در مورد حمایت برای ما ننوشتند.
در مورد اینکه آیا خود تحلیلگران متوجه می شوند که چه زمانی لازم است اسناد بنویسند و به روز شوند، توافق بسیار یکنواخت تر بود (1,33)، از جمله طراحی آن (1.07). آنچه در اینجا به عنوان یک ناراحتی به آن اشاره شد، نبود قوانین یکسان برای نگهداری اسناد بود. بنابراین، برای اینکه حالت "چه کسی به جنگل می رود، چه کسی هیزم می گیرد" روشن نشود، آنها باید بر اساس نمونه هایی از اسناد موجود کار کنند. از این رو، یک آرزوی مفید ایجاد استانداردی برای مدیریت اسناد و توسعه الگوهایی برای قطعات آن است.
مستندات برنامه های NIB در زمان ارائه برای پشتیبانی عملکردی (0.73) جاری است. این قابل درک است، زیرا یکی از معیارهای ارائه پروژه برای پشتیبانی عملکردی، اسناد به روز است. همچنین برای درک اجرای (0.67) کافی است، اگرچه گاهی اوقات سؤالات باقی می ماند.
اما آنچه پاسخ دهندگان با آن موافق نبودند (کاملاً به اتفاق آرا) این بود که مستندات برای برنامه های NIB، در اصل، فقط برای پشتیبانی عملکردی مورد نیاز است (-1.53). تحلیلگران اغلب به عنوان مصرف کنندگان اسناد ذکر می شدند. بقیه تیم (توسعه دهندگان) - خیلی کمتر. علاوه بر این، تحلیلگران بر این باورند که توسعه‌دهندگان از مستندات برای درک آنچه باید پیاده‌سازی کنند، استفاده نمی‌کنند، اگرچه نه به اتفاق آرا (-0.06). به هر حال، در شرایطی که توسعه کد و نوشتن مستندات به طور موازی پیش می‌رود، انتظار می‌رود.
نتیجه چیست و چرا به این اعداد نیاز داریم؟
برای بهبود کیفیت اسناد تصمیم گرفتیم موارد زیر را انجام دهیم:
- از توسعه دهنده بخواهید اسناد مکتوب را بررسی کند.
- در صورت امکان، ابتدا اسناد را به موقع به روز کنید.
- استانداردی برای مستندسازی پروژه‌های NIB ایجاد و اتخاذ کنید تا همه بتوانند به سرعت بفهمند کدام عناصر سیستم و دقیقاً چگونه باید توصیف شوند. خوب، قالب های مناسب را توسعه دهید.
همه اینها باید به ارتقای کیفیت اسناد به سطح جدیدی کمک کند.
حداقل من امیدوارم.
منبع: www.habr.com