پروژه بنیاد لینوکس

این صفحه شامل جزئیات یک پروژه نویسندگی فنی است که برای فصل اسناد گوگل پذیرفته شده است.

خلاصه پروژه

سازمان متن‌باز:

بنیاد لینوکس

نویسنده فنی:

بور

نام پروژه:

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

طول پروژه:

طول استاندارد (۳ ماه)

شرح پروژه

چکیده:

مستندات برای کمک به کاربران نهایی و توسعه‌دهندگان در استفاده از یک محصول یا سرویس طراحی شده‌اند. مستندات خوب بسیار مهم هستند زیرا مسیری را برای کاربران فراهم می‌کنند تا نحوه استفاده از یک نرم‌افزار، ویژگی‌ها، نکات، ترفندها و همچنین حل مشکلات رایج هنگام استفاده از نرم‌افزار را بیاموزند. همچنین هزینه‌های پشتیبانی را کاهش می‌دهد و بخشی از هویت شرکتی و متن‌باز محصول است: یک مستندات خوب نشانه سلامت محصول و تیم توسعه‌دهنده است.

بدون یک مستندسازی خوب، ممکن است کاربر نداند که چگونه موارد فوق را به طور مؤثر و کارآمد انجام دهد. مستندات می‌توانند نقش محوری در تضمین موفقیت یک محصول داشته باشند، زیرا ارتباطات عالی همیشه در قلب هر کسب‌وکار یا محصولی وجود داشته و خواهد داشت و یک مستندسازی عالی، آن ارتباطات را در یک چارچوب قابل مدیریت قرار می‌دهد که همه می‌توانند برای موفقیت به آن دسترسی داشته باشند.

هر سایت مستندسازی به یک خط لوله گردش کار خوب برای ساخت و میزبانی نیاز دارد، در سازمانی مانند AGL، با نسخه‌های متعدد و مستندات مفصل فراوان، فایل‌های مستندسازی (markdowns) در مخازن متعدد پخش شده‌اند و وظیفه نگهداری و به‌روزرسانی آنها را فوق‌العاده پیچیده و زمان‌بر می‌کنند.

وضعیت فعلی:

• وب‌سایت AGL doc بر اساس مجموعه‌ای از فایل‌های markdown است که از مخازن مختلف جمع‌آوری شده‌اند.
• صفحات سند در حال حاضر با استفاده از موتور پروژه کوردووا، به صورت markdown در منابع جداگانه میزبانی می‌شوند.
• این منجر به راه‌اندازی چهار مخزن برای فرآیند ساخت و میزبانی مستندات می‌شود:
• Docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] : شامل قالب وب‌سایت Jekyll است.
• Docs-tools [https://github.com/automotive-grade-linux/docs-tools]: شامل ابزارهایی برای تولید خودکار یک وب‌سایت فنی از فایل‌های Markdown است.
• Docs-sources [https://github.com/automotive-grade-linux/docs-sources]: منبع (markdowns [https://github.com/automotive-grade-linux/docs-sources/tree/master/docs]) برای اسناد عمومی و راهنماها.
• Docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] : مخزن صفحات گیت‌هاب مستقر شده برای سایت مستندات [https://gist.github.com/growupboron/docs.automotivelinux.org].
• ابزاری (اسکریپت) که در docs-tools [https://github.com/automotive-grade-linux/docs-tools] موجود است، وظیفه جمع‌آوری و قالب‌بندی تمام فایل‌های markdown را بر اساس fetched_files.yml واقع در docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] بر عهده دارد.
• گردش کار فعلی تولید وب‌سایت مستندات agl: current_workflow [https://drive.google.com/file/d/1OSwkVWFcsajgCOjbtdPf42EIfpidUJ0U/view?usp=sharing]
• فایل section_version.yml شامل لینک‌های تمام فایل‌های yaml کتاب است و سپس تمام فایل‌های yaml کتاب را از مخازن راه دور به docs-webtemplate [https://github.com/automotive-grade-linux/docs-webtemplate] منتقل می‌کند. فایل‌های yaml کتاب شامل تمام آدرس‌های اینترنتی (url) فایل‌های markdown شما از مخزن راه دور هستند.
• به محض اینکه تمام فایل‌های markdown دریافت شدند، ابزارها برای تولید وب‌سایت سند AGL در docs-gh-pages [https://github.com/automotive-grade-linux/docs-gh-pages] که به طور مشابه مستقر شده است، پردازش می‌شوند.
• روند فعلی نگهداری از خط تولید، به خصوص برای مشارکت‌کنندگان جدید، برای کاربر و توسعه‌دهنده خوشایند نیست. این خط تولید گردش کار (ساخت و میزبانی) می‌تواند بسیار ساده‌تر و کارآمدتر شود تا توسعه‌دهندگان بتوانند به جای حفظ تولید مستندات و گردش کار استقرار، بر بخش مستندسازی تمرکز کنند.