پروژه کولیبری

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

خلاصه ی پروژه

سازمان منبع باز:

کولیبری

نویسنده فنی:

استف دیکس

نام پروژه:

سبک مستندسازی اکوسیستم کولیبری و کنوانسیون گردش کار

طول پروژه:

دویدن طولانی مدت (5 ماه)

شرح پروژه

خلاصه

این سند جزئیات پیاده‌سازی دستورالعمل‌های سبک و مدیریت گردش کار به اطلاعات مستند آموزش برابری برای پروژه اکوسیستم کولیبری را شرح می‌دهد.

بررسی اجمالی

پیشنهاد من شامل چهار مرحله است. در مرحله اول، راهنمای سبک مستندسازی LE را با دستورالعمل‌های دسترس‌پذیری، نوشتن و توصیه‌های قالبی با پیروی از مفاهیم LE و دستورالعمل‌های سبک در توسعه نرم‌افزار تکمیل می‌کنم. در مرحله دوم، یک ممیزی کیفیت بر روی اسناد ReadTheDocs و GoogleDocs انجام خواهم داد. برنامه حسابرسی استفاده از چک لیست ها را برای ارزیابی انطباق با دستورالعمل های سبک یکپارچه می کند. این چک لیست ها به ثبت یافته ها و اعمال تغییرات در اسناد کمک می کند. در مرحله سوم، من روی ساختار، ظاهر و احساس قالب ها از اسناد ReadTheDocs و GoogleDocs کار خواهم کرد. من یک مخزن الگو و تصاویر در Google Drive ایجاد خواهم کرد که هر دسته الگو از انواع اسناد اصلی را برای استفاده مجدد در پیاده سازی های بعدی شناسایی می کند. من این کار را تکمیل خواهم کرد و الگوهایی را برای ارائه مشکلات سند برای شناسایی آسان در بررسی درخواست کشش تکمیل خواهم کرد. در نهایت، من یک راهنمای مشارکت‌کنندگان ایجاد خواهم کرد که منابع مفیدی را برای هر گروه از همکاران گروه‌بندی می‌کند تا تجربه دسترسی به اطلاعات را افزایش دهد.

هدف و دامنه

هدف این طرح اجرایی بهبود تجربه کاربران نهایی با استفاده از اسناد کولیبری و کمک به اعضای تیم و مشارکت کنندگان برای تولید مستندات بهتر و همکاری فعال در جامعه است. این پیاده سازی برای ReadTheDocs و زیر مجموعه های اسناد Google Docs در اکوسیستم Kolibri اعمال می شود.

حضار

مخاطبان اصلی از مجریان، مدیران و کاربران نهایی که مهم ترین مصرف کنندگان اسناد کولیبری هستند. مخاطب ثانویه از اعضای تیم و همکاران برای تولید و استفاده از مستندات کولیبری.

اهداف

راهنمای سبک و سیستم گردش کار برای Kolibri Ecosystem Documentation از کاربران انتظار دارد: اسناد قابل هضم را با زبانی قابل دسترس و طرح‌بندی ثابت بسازند. حفظ شیوه های کیفیت بر اساس مستندات. دسترسی آسان به اطلاعات بین کانال های مستندسازی را حفظ کنید. ابتکارات مشترک را در جامعه منبع باز Kolibri تقویت کنید.

منبع اطلاعات

منابع اطلاعاتی من Kolibri، Kolibri Studio، اسناد RTD توسعه Kolibri، و Kolibri Toolkits از Google Drive بودند.
رادینا ماتیچ فوق العاده کمک بزرگی در ارائه فعالیت های گرم کردن و فعالیت های خاص پروژه بود. نظرات او در مورد آنچه که سازمان به عنوان "راهنماها" و "راهنماها" مفهوم سازی می کند و در مورد وجود یک راهنمای برای مشارکت کنندگان به من کمک کرد تا ایده های خود را سازماندهی کنم و پیش نویس نتیجه گیری را انجام دهم.

نرم افزار

من پیش نویس Style Guide را در Google Docs توسعه خواهم داد. این پلت فرم سند برای تکرار در حالی که آماده انتشار است عالی است. برای ممیزی QA، از Google Forms برای انجام و ارزیابی اسناد استفاده خواهم کرد. یک صفحه گسترده پاسخ های فرم را برای کنترل سند ذخیره می کند. من اسناد RTD را با استفاده از GitHub بازسازی خواهم کرد. من با Git، Gitkraken، GitHub و Gitlab کار کرده ام. من دانش کاری در مورد Markdown و چند RestructuredText دارم. من در حال برنامه ریزی برای کمک به اصلاح اسناد برای ادامه یادگیری نحو هستم. من از Sharex برای تصاویر و گیف استفاده خواهم کرد. من عاشق این ابزار هستم زیرا در فرمت های خروجی مختلف رندر می شود. من از Diagrams برای نمودار و ویرایش تصاویر استفاده خواهم کرد. نرم افزار Diagrams به زیبایی با GoogleDocs، Google Drive و LibreOffice ادغام می شود. وضعیت اسناد در مرحله اکتشاف، بیشتر اسناد کولیبری را اصلاح کردم. من اشتباهات گرامری، غلط املایی، ناهماهنگی در چیدمان، تایپوگرافی، استفاده از تصویر، و همچنین مسیرهای مستندسازی گیج کننده را در اکثر اسناد پروژه پیدا کردم. به عنوان مثال، در راهنمای کاربر کولیبری، بخش عیب یابی یک موضوع فرعی است و یک موضوع نیست. این اطلاعات به اندازه کافی حیاتی است تا کاربران نهایی بتوانند از فهرست مطالب به آن دسترسی داشته باشند. به عنوان جایگزین دوم، آنها می توانند از نوار جستجو و درخت فهرست مطالب برای گسترش سایر موضوعات و یافتن مقالات عیب یابی استفاده کنند.

برای دسترسی به بخش "عیب یابی" باید آن را جستجو کنید یا "Manage Kolibri" را گسترش دهید تا متوجه شوید که عیب یابی به عنوان بخشی از مستندات وجود دارد. راهنما در مقابل دستورالعمل برای این پیشنهاد پروژه، من دو سند را تجزیه و تحلیل کردم: راهنمای سبک مستندسازی کاربر LE Kolibri و دستورالعمل‌های ترجمه LE. در راهنمای LE Kolibri، من توصیه‌ها و نظراتی را از طرح موضوع پیشنهادی و طرح مستندسازی به‌علاوه چند چیز دیگر که نیاز به بهبود در راهنما دارند، ارائه کردم. برای دستورالعمل‌های ترجمه LE، قالب و سبک را بر اساس توصیه‌هایم و قراردادهای موجود در راهنمای سبک تغییر دادم. آنچه در طول تجزیه و تحلیل بیشتر مورد توجه من قرار گرفت، تصور غلطی بود که بین اسناد دسته بندی شده به عنوان راهنما و دستورالعمل وجود دارد.

عواقب

من علاوه بر پیشنهادات و نظرات با یک فرم اولیه که در تکلیف QA Audit با جزئیات بیشتر توضیح می‌دهم، راهنمای ترجمه LE را بررسی کردم. اینها برخی از نظرات نهایی به دست آمده از ارزیابی هستند: پیوندهای شکسته برای وب سایت ICU Syntax .js قالب استفاده شده برای ایجاد این دستورالعمل ها نادرست است. این سند یک راهنما است، نه دستورالعمل. تایپوگرافی ناسازگار استفاده نادرست از عنوان و عنوان، استفاده نادرست از زبان و استفاده نادرست از انقباضات. استفاده نادرست از متون جایگزین بیش از اظهارات / دستورالعمل های مکرر.

یافته‌های هر دو سند بخشی از موارد تحویلی این پیشنهاد است.

وظایف خاص پروژه

• توصیه‌های راهنمای سبک مستندسازی کاربر LE (نظرات)
• دستورالعمل های ترجمه LE با سبک ها و قالب های جدید.
• طرح کلی موضوع
• جدول زمانی پروژه
• وظایف مستندسازی