مستندات تک منبع: نحوه نوشتن و انتشار در همه جا.

مقدمه

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

وارد تک منبع شوید: این یک استراتژی مستند سازی است که به کسی اجازه می دهد یک بار محتوا بنویسد و در همه جا منتشر کند. در این مقاله ، ما بررسی خواهیم کرد:

چه منابع واحد است؟

چرا مهم است؟

چگونه می توانیم آن را برای ساده تر کردن گردش کار اسناد شما پیاده سازی کنیم؟

معنی تک منبع

 Single sourcing is the practice of creating modular,reusable  content that can be published in multiple formats without redundant effort.instead of duplicating content across different techniques,automation and specialized tools to generate multiple outputs from a single content source.

چرا تک منبع اهمیت دارد؟
استفاده از این رویکرد مزایای مختلفی را ارائه می دهد:

1ثبات: این پیام های یکنواخت را در تمام قالب های مستندات تضمین می کند.

2همکاری: به خوبی در جریان کار Docs-as Code کار می کند و با GIT و CI/CD ادغام می شود.

3کارایی: زمان صرف شده برای به روزرسانی محتوا را در مکان های مختلف کاهش می دهد.

4انعطاف پذیری: از خروجی های مختلف (HTML ، PDF ، اسناد API) و غیره با تلاش کمی پشتیبانی می کند.

نحوه حمل تک منبع

 Here are step-by-step process to transition to single-source documentation approach:

• نوشتن ماژولار
  تجزیه مستندات در مؤلفه های کوچک و قابل استفاده مجدد که می توانند در چندین خروجی دوباره قرار بگیرند.

• از متن و فیلتر مشروط استفاده کنیدبشر
  برای سفارشی کردن محتوا برای مخاطبان/خوانندگان مختلف از سیستم های برچسب گذاری یا ویژگی های متن شرطی استفاده کنید (به عنوان مثال کاربران شرکت رایگان در مقابل شرکت).

جدیدانتشار خودکار با خطوط لوله CI/CD
برای خودکار سازی ساخت و سازه های مستندات ، از GitHub Action ، Jekins یا Gitlab CI استفاده کنید.

• قالب های خروجی سمت راست را انتخاب کنید
  تصمیم بگیرید که اسناد شما برای پشتیبانی از کدام قالب نیاز دارد: مستندات مبتنی بر وب (HTML ، MD) برای پایگاه های دانش آنلاین.

1.pdf-برای کتابچه های قابل بارگیری.

2.IN-APP TIPOLING TIPS- CONTEXT- کمک حساس.

1. مستندات API (Swagger ، API باز): برای مرجع توسعه دهنده.

چالش ها و بهترین شیوه ها.

While  single-sources has advantages it also includes challenges.

• منحنی یادگیری*: ابزارهایی مانند DITA و MADCAP نیاز به آموزش دارند.

مدیریت مستندات در مقیاس بزرگ: به یک استراتژی محتوای خوب ساختار یافته نیاز دارد.

• تضمین انعطاف پذیری: متعادل کردن قابلیت استفاده مجدد با سفارشی سازی.

پایان
Single -Sourcing یک تغییر دهنده بازی برای نویسندگان فنی است که به دنبال بهینه سازی جریان کار هستند. با تعادل در نوشتن ماژولار ، اتوماسیون و ابزارهای مناسب ، می توانید مستندات با کیفیت بالا و سازگار را در بسیاری از پلتفرم ایجاد کنید. آیا در حال حاضر از تکنیک های تک منابع استفاده می کنید؟ در نظرات به من اطلاع دهید!