این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.
خلاصه پروژه
- سازمان منبع باز:
- CERN-HSF
- نویسنده فنی:
- سابیتا آر
- نام پروژه:
- بازسازی و ساده سازی اسناد مربع آلپیکس
- طول پروژه:
- طول استاندارد (3 ماه)
شرح پروژه
نمای کلی من پروژه Allpix Squared CERN-HSF را به دو دلیل اصلی انتخاب کردم:
مهارت‌سازی: مستندات موجود این پروژه جامع است و قالب‌های محتوایی متعددی را ادغام می‌کند. ممیزی و بازسازی این مجموعه اسناد گسترده به من کمک می کند تا معماری اطلاعات و مهارت های نوشتاری خود را بهبود بخشم. علاوه بر این، دامنه پروژه (فیزیک ذرات!) برای من جدید است. من را به چالش می کشد تا مهارت های تعامل با توسعه دهنده خود را تقویت کنم. من معتقدم که نویسندگان فنی می‌توانند ورودی‌های توسعه‌دهندگان را پردازش کنند و محتوای مفیدی را برای هر سطحی از کاربران ارائه کنند، در صورتی که تحقیقات پیش‌زمینه مورد نیاز خود را انجام دهیم و سؤالات درست را بپرسیم. این پروژه به من اجازه می دهد این نظریه را آزمایش کنم!
دانش فنی: این پروژه به Hugo نیاز دارد - ابزاری که در بالای لیست یادگیری من قرار دارد. من مشتاقانه منتظر یادگیری گردش کار LaTeX-Markdown-Hugo-GitLab-CI هستم.
در طول مرحله کاوش نویسنده فنی، به طور خلاصه با مربیان پروژه تعامل داشتم و با ساختار مجموعه اسناد موجود آشنا شدم. من همچنین یک وب‌سایت آزمایشی (https://ap2-demo.netlify.app/) ساختم تا آزمایش کنم آیا می‌توانم Hugo و Docsy را به درستی روی دستگاه ویندوز خود پیکربندی کنم یا خیر. من توانستم وب سایت را در Netlify مستقر کنم اما در Gitlab Pages نه. برای اینکه این پروژه گردش کار استقرار فعلی خود را حفظ کند، من راهی برای استقرار تم Hugo Docsy در صفحات Gitlab پیدا خواهم کرد.
نتایج مورد انتظار پروژه - یک وب سایت پروژه ساده که اسناد، مرجع کد، آموزش ها و اخبار را یکپارچه می کند. - یک کتابچه راهنمای کاربر بازسازی شده و بازبینی شده که محتوای در نظر گرفته شده برای کاربران و توسعه دهندگان را از هم جدا می کند و شامل اطلاعات گم شده قبلی است. - گردش کار آموزش از نمونه‌های موجود از نحوه مستندسازی، پرسش‌های متداول و مسائل رایج.
ابزار پروژه اسناد فعلی Allpix Squared علاوه بر GitLab و Gitlab CI از LaTeX، Doxygen، pandoc و Hugo استفاده می کند. من و مربیان پروژه در مورد احتمال انتقال محتوا از LaTeX به Markdown با افزونه های MathJax صحبت کرده ایم. اگر موفق شوم، گردش کار doc شامل Hugo، Markdown، Doxygen، git و Gitlab CI می شود. برای نگه داشتن آموزش ها در همان وب سایت/پلتفرم، از Hugo و Markdown استفاده می کنم. من در مورد امکان استفاده از Codelabs-as-a-tool (ClaaT) برای آموزش کنجکاو هستم. در جولای امسال، امیدوارم بتوانم گردش کار ClaaT-Hugo را آزمایش کنم و در صورت انتخاب با مربیان در مورد آن بحث کنم.
مدت زمان پروژه من درخواست می کنم پروژه Allpix Squared را در یک دوره استاندارد سه ماهه (14 سپتامبر 2020 - 30 نوامبر 2020) تکمیل کنم، که در طی آن تقریباً هزینه خواهم کرد. 15 ساعت در هفته روی آن. در صورت نیاز، این ساعات شامل جلسات مربی و ایمیل‌های مرتبط خواهد بود. من به جدول زمانی GSoD برای پیوند جامعه و نهایی کردن پروژه نیز پایبند خواهم بود.
وظایف پروژه به این صورت است که قصد دارم به‌روزرسانی‌های پیشنهادی خود را برای مجموعه اسناد Allpix Squared موجود پیاده‌سازی کنم: 1. تحقیق، بحث و بررسی گزینه‌ها (17 اوت - 13 سپتامبر 2020): - درک الزامات پروژه - نصب نرم‌افزار Allpix Squared برای شناسایی اطلاعات گم شده، در صورت وجود، در اسناد فعلی. - مدارک لازم را بخواهید. - ایجاد گردش کار کاربر برای کاربران مختلف Allpix Squared - طبقه بندی محتوا بر اساس نقش کاربر - بررسی پیامدهای تبدیل فایل های LaTeX به Markdown - یکپارچه سازی مخازن منبع یا درک نحوه کار با چندین مخزن git - پاداش: تست CLaaT به عنوان گزینه ای برای آموزش - امتیاز: یک راهنمای سبک سریع/مرجع کدهای کوتاه برای کمک به مشارکت کنندگان در حفظ اسناد جدول زمانی: مرحله پیوند با جامعه
تجدید ساختار، بررسی و بهبود محتوا (14 سپتامبر - 19 اکتبر 2020): دو کار در هفته، تقریباً 5-7 ساعت برای هر کار. این جدول زمانی شامل یک هفته بافر برای رسیدگی به تاخیرها یا مشکلات غیرمنتظره است.
- محتوای موجود و طبقه بندی کاربران را با در نظر گرفتن گردش کار کاربر مرور کنید
- گردش کار محتوای بازسازی شده را برای کاربران مختلف ترسیم و آزمایش کنید
- محتوای گمشده را منبع و تقویت کنید
- فایل های LaTeX را به Markdown تبدیل کنید
- فهرست محتویات راهنمای کاربر و راهنمای توسعه دهنده را نهایی کنید
- فایل های PDF راهنمای کاربر و توسعه دهنده را تولید کنید
- پاداش: ساختار محتوا برای آموزش از مثال ها و مسائل
- پاداش: تنظیم یک گردش کار آموزشی برای مثال‌های نحوه انجام جدول زمانی: 5 هفته (مرحله توسعه سند)
ساخت وب سایت (19 اکتبر - 30 نوامبر 2020): 1-2 کار در هفته، تقریباً 5-7 ساعت برای هر کار. این جدول زمانی شامل یک هفته بافر برای عیب یابی مشکلات و تنظیم دقیق خروجی نهایی است.
- گردش کار انتشار را درک و آزمایش کنید
- یک ساختار وب سایت با استفاده از Hugo و Docsy بسازید
- نحوه حفظ استقرار خودکار و گردش کار فعلی را با استفاده از Docsy آزمایش کنید
- مطالب را از داکسیژن بیرون بکشید
- کتابچه راهنمای کاربر، راهنمای توسعه‌دهنده، و آموزش‌هایی را از محتوای LaTex یا Markdown تهیه کنید
- ظاهر و ظاهر وب‌سایت پروژه را نهایی کنید (لوگو، رنگ‌ها، الگو، طرح‌بندی، پیوندها، قابلیت استفاده و Gitlab CI/CD) جدول زمانی: 6 هفته (مرحله توسعه سند)