پروژه GenPipes

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

خلاصه ی پروژه

سازمان منبع باز:
جن پایپس
نویسنده فنی:
شالو
نام پروژه:
اسناد GenPipes را در «Read The Docs» تنظیم کنید
طول پروژه:
طول استاندارد (3 ماه)

شرح پروژه

من یک طرح 3 مرحله ای را برای دستیابی به هدف تنظیم اسناد GenPipes در "Read The Docs" پیشنهاد می کنم.

مرحله 1: PoC

  • اسناد موجود GenPipes را به عنوان یک کاربر / محقق جدید بررسی کنید

    • اطلاعات گمشده، نادرستی را شناسایی کنید
    • پیشنهاد موضوعات سند جدید (در صورت نیاز)
    • پیش نویس نقشه معماری اطلاعات برای مخاطبین هدف، با تمرکز بر کاربران جدید.

    (توجه: در طول این مرحله، ممکن است به ورودی‌های مربیان GenPipes در رابطه با راه‌اندازی مخزن جدید GitHub نیاز داشته باشیم که در آن اسناد genpipes برای RTD می‌توانند میزبانی شوند. این مخزن GitHub می‌تواند برای وارد کردن همه اسناد در خطوط لوله ساخت RTD استفاده شود. ممکن است نیاز به اطلاعاتی درباره قوانین مخزن GenPipes و دستورالعمل‌های مدیریت منبع سند در صورت لزوم رعایت شود. در غیر این صورت می‌توان از موارد استاندارد استفاده کرد، afaik. همچنین برای PoC، می‌توانم یک نمونه راه‌اندازی مخزن RTD را با استفاده از حساب GitHub خود - به عنوان مثال، https://gpdocs نمایش دهم. .readthedocs.io/en/latest/ - این نمونه‌ای است که من برای این پیشنهاد ایجاد کردم)

  • بر اساس بررسی و تجزیه و تحلیل در مرحله قبل، یک اسکلت بدون ساختار از ساختار / نمایه اسناد GenPipes پیشنهادی ایجاد کنید و آن را در سایت RTD قرار دهید.

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

  • بررسی / دریافت تاییدیه در TOC اسکلت barebones

    در طول مرحله ارزیابی GenPipes GSoD، من سعی کردم از طریق این نمونه میزبانی شده در RTD برای GenPipes ارزش ایجاد کنم. لطفاً توجه داشته باشید، این فقط برای اهداف آزمایشی است، پیوند محافظت شده، هنوز به طور عمومی در RTD فهرست نشده است. صرف نظر از اینکه در فهرست نهایی قرار بگیرم، این نسخه ی نمایشی می تواند برای شروع کار GenPipes RTD استفاده شود. من قبلاً منابع موجود در مخزن c3g/GenPipes GitHub را بررسی کرده ام. مربیان، رولا و هکتور آن را در جریان بحث «اشتراک‌گذاری صفحه» اسکایپ قبلاً دوست داشتند و بنابراین فکر کردم شاید خدایان GSoD هم بخواهند آن را ببینند. اسکلت آن در حال حاضر بدون استخوان است، اما من قصد دارم تا 30 جولای تا 30 ژوئیه آن را به‌روزرسانی کنم.

https://genpipes.readthedocs.io/en/latest/

مرحله 2: ایجاد Docset GenPipes Doc v0.9

  • با در نظر گرفتن جدول زمانی GSoD، شناسایی کنید که کدام اسناد GenPipes فعلی یا موجود را می توان وارد کرد، پیوند داد یا به اسناد مبتنی بر Sphinx/rst برای میزبانی در RTD تبدیل کرد.

  • اسناد شناسایی شده را به فرمت rst تبدیل کنید، در صورت نیاز، اسناد جدید را در صورت لزوم ایجاد کنید، از هر آنچه که ممکن است / مرتبط استفاده مجدد کنید.

    • این مجموعه سند اولیه را به عنوان اثبات مفهوم در ReadTheDocs وارد کنید - آن را به عنوان یک مخزن محافظت شده در آنجا میزبانی کنید. یک یادداشت از قبل بگذارید و به کاربران جدید پیشنهاد دهید تا زمانی که بررسی/سوئیچ رسمی به اسناد اصلی GenPipes مراجعه کنند.

  • بررسی / دوره - صحیح / به روز رسانی

مرحله 3: اصلاح، بررسی و انتشار اولین پیش نویس در RTD

  • جزئیات ساختار سند جدید پیشنهادی GenPipes را در GenPipes TOC پر کنید – علاوه بر چند مورد اول (GenPipes Readme)، مفاهیم، ​​آموزش و غیره، اسناد اضافی اضافه کنید.

  • برای آدرس دادن به کاربران جدید، کاربران باتجربه GenPipes، توسعه دهندگان GenPipes و غیره، مرزبندی واضح را در TOC اضافه کنید.

  • در مورد نحوه نگهداری اسناد GenPipes، ویرایش توسط کاربران و اینکه آیا C3G این امکان را برای مشارکت‌کنندگان سند خارجی فراهم می‌کند، پیشنهاد کنید، درباره یک فرآیند کار با اتوماسیون قطعات از طریق RTD (ساخت‌های ابوالهول) صحبت کنید. این ممکن است نیاز به ایجاد برخی دستورالعمل‌ها برای به‌روزرسانی‌های سند مشابه دستورالعمل‌های کدنویسی داشته باشد. ممکن است به مراحل فرعی بیشتری نیاز داشته باشد. به عنوان مثال، بررسی خودکار املا قبل از تأیید روابط عمومی در اسناد GenPipes.

گزارش

در نهایت، یک گزارش برای GSoD بر اساس تجربیات، گزارش‌ها، بازخورد مربیان ایجاد کنید.

افکار دیگر

در آینده (بیش از 3 ماه)، در صورت امکان، می توانم به حفظ این برای GenPipes در طولانی مدت کمک کنم. یا در صورت لزوم، دیگران را برای همین کار آموزش دهید. ما می توانیم این را بر اساس نتیجه این 3 ماه اول بفهمیم.

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

همین پیشنهاد و چگونگی پیدایش آن (تاریخچه) را نیز می‌توانید در https://drive.google.com/file/d/1oKVp_7ZeYGMxhynfc97qUUcGNh2CNbX0/view?usp=sharing مشاهده کنید