برای بسیاری از وبسایت‌ها داشتن مستندات یکپارچه ضروری و بسیار مهم است. درست همانطور که فرایند کدنویسی نیاز به تمیز نوشتن و نگهداری درست دارد، مستندات سرویس‌ها و محصولات نیز به این میزان از مراقبت نیاز دارند. اما چالشی که وجود دارد این است که چنین باوری به یک باور عمومی در بین شرکت‌ها تبدیل نشده است: آنقدری که کدها به‌خوبی نگهداری و توسعه داده می‌شوند، مستندات به‌خوبی پیش نمی‌روند. راهکار این مسئله کمک گرفتن از رویکرد Docs-as-Code است.

منظور از رویکرد Docs-as-Code چیست؟

در رویکرد Docs-as-Code، مستندات در جریان توسعه کدنویسی و افزودن ویژگی‌های جدید به محصولات به‌صورت هماهنگ توسعه داده می‌شوند. چالش اصلی این موضوع در همان هماهنگی بین تیم‌های توسعه و تیم مستندات است. برای حل این مشکل Docs-as-Code رویکردی را پیشنهاد می‌دهد که در آن مستندنویسان برای ساختن مستندات‌شان نیاز دارند که از همان ابزارهایی استفاده کنند که توسعه‌دهندگان برای پیشبرد محصول از آن‌ها بهره می‌گیرند.

برای مثال گیت از جمله پرکاربردترین ابزارهای مدیریت نسخه در بین توسعه‌دهندگان است. در این حالت با هر بار Commit کُد توسط توسعه‌دهنده، مستندنویس براساس آن، مستندات جدیدی نوشته و روی ریپو مستندات قرار می‌دهد.

در چنین رویکردی فضای همکاری به قدرت خود پیش خواهد رفت و همچنین هماهنگی‌های لازم در همان فضای کدنویسی صورت می‌گیرد.

چرا باید از Docs-as-Code استفاده کنیم؟

برای درک چرایی استفاده از Docs-as-Code باید به سناریوهای قدیمی فکر کنیم. سناریویی که مشکلات زیر در آن وجود داشت:

• بواسطه نبود فرهنگ سازمانی Docs-as-Code، مسئول مشخصی (یا تیم مشخصی) برای مستندات پیدا نمی‌شد. حال در رویکرد Docs-as-Code نیاز است که حتما چنین فرد یا تیمی به‌صورت یکپارچه روی مستندات کار کند.
• نبود فضای همکاری در بین تیم‌های مختلف بدلیل استفاده از ابزارهای متفاوت، چالش اصلی سناریوهای قدیمی بود. استفاده از Microsoft Office و کُپی کردن محتوا روی وبسایت و تکنیک‌هایی از این دست فضای همکاری را واقعا دشوار کرده و در نتیجه یکپارچگی کُد و مستندات را برهم می‌زند.
• پیگیری تغییرات در نبود فضای یکپارچه، چالش دیگر سناریوهای قدیمی بود. با هر بار تغییر در کدبیس مستندنویس باید زمانی را برای هماهنگی با برنامه‌نویسان در نظر می‌گرفت و کدها را از آن‌ها دریافت می‌کرد. در نتیجه خودکارسازی کارها کمتر اتفاق می‌افتاد و بیشتر فرایندها به‌صورت دستی پیش می‌رفت.

Docs-as-Code روی یکپارچه‌سازی فضای توسعه و مستندات تمرکز دارد. در نتیجه با ایجاد هماهنگی بین تیم‌های مختلف این امکان را فراهم می‌کند تا روی مستندات تمرکز بیشتری داشته باشیم و تعاملات مستقیم با خود برنامه‌نویسان را برای دریافت تغییرات و اطلاع از چنین مواردی کمتر کنیم. در نتیجه زمان بسیاری صرف نخواهد شد.

ابزارهای لازم برای Docs-as-Code

برای بهره‌گیری از رویکرد Docs-as-Code یادگیری و استفاده از چند ابزار بسیار ضروری است:

• یک IDE یا کد ادیتور با قابلیت پشتیبانی از Markdown
• یادگیری و استفاده از static site generatorهایی مانند (Sphinx, Hugo)
• توانایی کار با فضاهای میزبانی وبسایت‌های استاتیک hosting platform مانند (GitHub Pages, Netlify)
• یادگیری Git و سرویس‌هایی مانند Github و Gitlab
• یادگیری و به‌کارگیری CI/CD و ابزارهایی مانند (Jenkins, GitHub Actions)

بهترین نکات برای اجرا کردن Docs-as-Code

• با جریان به‌روزرسانی‌های کدبیس پیش برید: هدف اصلی Docs-as-Code ایجاد هماهنگی بیشتر بین تیم توسعه و تیم مستندات است. در نتیجه با به‌روزرسانی‌های کدبیس حتما مستندات را آپدیت کنید. جدای از آن برای هرچه بهتر کردن مستندات تلاش کنید و مستندات قبلی را در بازه‌های زمانی مختلف بررسی و بهینه کنید.
• مستندات قدیمی را حذف کنید: با ایجاد تغییرات در محصول و حذف ویژگی‌ها، نیاز است که مستندات مربوط به آن نیز کاملا حذف شود. در نتیجه هیچوقت مستندات قدیمی را نگهداری و حتی آرشیو (با قابلیت دسترسی عموم) نکنید.
• از تکنیک‌های نوشتن به زبان ساده استفاده کنید: خواه مخاطب شما عمومی باشد و خواه فنی، نیاز است که مستندات با ساده‌ترین زبان ممکن نوشته شود. این موضوع وابستگی فرد استفاده کننده را به سرویس پشتیبانی کمتر از هر زمانی می‌کند. کاری کنید مستندات بهترین منبع برای یادگیری استفاده از سرویس شود و به تمام مشکلات آدرس بدهد.
• پروسه‌ها را خودکارسازی کنید: تا جایی که ممکن است از انجام فرایندهای دستی که رویکردی برای خودکارسازی آن وجود دارد پرهیز کنید. به‌جای پیام فرستادن به توسعه‌دهنده برای بررسی کد جدید، ریپو را مطالعه کنید، فرایند دیپلوی کدها را در یک بستر CI/CD پیش ببرید و از حالت‌های قدیمی برای استقرار مستندات جدید استفاده نکنید.

در پایان

Docs-as-Code تلاش دارد تا رویکردی را برای هر چه بهتر پیش‌بردن مستندات سرویس‌ها ارائه کند. با بهره‌گیری از تکنیک‌ها و استانداردهای Docs-as-Code می‌توانید توسعه مستندات را با بیشترین هماهنگی با بخش کدنویسی پیش ببرید. برای مطالعه و آموزش بیشتر در زمینه Docs-as-Code می‌توانید به این منبع آموزشی مراجعه کنید.