مستندسازی یک ویژگی است
مستندسازی از محصول شما جدا نیست؛ بلکه بخشی از محصول است.
بسیاری از توسعهدهندگان از الگوی اشتباهی پیروی میکنند:
- ساخت ویژگی.
- تست ویژگی.
- عرضه ویژگی.
- مستندسازی ویژگی.
کاربران کد شما را تجربه نمیکنند. آنها رابط کاربری، جریانهای کاری و مستندات شما را تجربه میکنند. از نظر کاربر، مستندات یک ویژگی است.
سازندگان از مستندسازی غافل میشوند چون خودشان محصول را درک کردهاند. شما میدانید چرا تصمیمات خاصی گرفتهاید. میدانید API چگونه کار میکند. میانبرها را میشناسید.
اما کاربر اینطور نیست. آنچه برای شما بدیهی به نظر میرسد، برای آنها مرموز است.
سوالات تکراری را به عنوان «بدهی مستندسازی» در نظر بگیرید. اگر افراد یک سوال را دو بار بپرسند، شما با یک مشکل روبرو هستید. یا محصول شما گیجکننده است یا مستندات شما ناقص است. گاهی اوقات نیاز است API را اصلاح کنید، اما اغلب، باید مستندات را اصلاح کنید.
مستندات خوب اصطکاک را کاهش میدهد و به این سوالات به سرعت پاسخ میدهد:
- این چیست؟
- چرا باید از آن استفاده کنم؟
- چگونه شروع کنم؟
- بهترین رویکرد چیست؟
- یک مثال ساده چیست؟
هدف، کامل بودن نیست؛ هدف، ایجاد شتاب است.
مستندات عالی، الگوها و هدف را آموزش میدهند. توضیح میدهند که چرا یک framework به روش خاصی کار میکند. این کار باعث میشود کاربران کارآمدتر شوند.
مستندات به روشهای نامحسوسی بر کسبوکار شما تأثیر میگذارند:
- نرخ پذیرش (Adoption rates).
- سرعت آنبوردینگ (Onboarding speed).
- هزینههای پشتیبانی.
- رشد جامعه کاربری.
- تجربه توسعهدهنده (Developer experience).
شما نمیتوانید تأثیر مستندات خوب را به راحتی مشاهده کنید، اما متوجه نبودِ مستندات بد بلافاصله میشوید.
به یاد داشته باشید که مستندسازی برای خودتان هم است. مستندات، دانش شما را برای نسخههای آیندهی خودتان حفظ میکند. تصمیمات را ثبت میکند تا مجبور نباشید ماهها بعد دوباره به دنبال پاسخها بگردید.
کیفیت محصول و کیفیت مستندات به هم پیوستهاند.
- نرمافزار گیجکننده به مستندات بیشتری نیاز دارد.
- نرمافزار شفاف به مستندات کمتری نیاز دارد.
- مستندات خوب، طراحی بد را آشکار میکند.
از برخورد با مستندسازی به عنوان یک موضوع فرعی دست بردارید. از آن برای اجبار به شفافیت استفاده کنید. شفافیت، طراحی شما را بهبود میبخشد. طراحی بهبودیافته، محصول شما را ارتقا میدهد.
منبع: https://dev.to/stinklewinks/documentation-is-a-feature-228n