این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.
خلاصه ی پروژه
- سازمان منبع باز:
- CERN-HSF
- نویسنده فنی:
- آریادنه
- نام پروژه:
- Rucio - اسناد Rucio را مدرن کنید (تجدید ساختار و بازنویسی کنید).
- طول پروژه:
- طول استاندارد (3 ماه)
شرح پروژه
چکیده: چارچوب Rucio با هدف مدیریت و سازماندهی حجم زیادی از داده های علمی توزیع شده جغرافیایی در مراکز داده ناهمگن توسعه یافته است. این چارچوب با ارائه قابلیت هایی مانند بازیابی داده های توزیع شده و تکرار تطبیقی، بسیار مقیاس پذیر، ماژولار و قابل توسعه است. مصرف کنندگان اسناد برای چنین خدماتی از پیشینه های مختلف هستند و هنگام دسترسی به آن نیازمندی های متفاوتی دارند. بنابراین، مستندات خوب برای چنین سرویسی باید پذیرش و استفاده از آن را برای کاربران نهایی ساده کند و در عین حال مرجعی برای مشکلات رایج و عیب یابی باشد.
در غیاب چنین مستنداتی، موانع قابل توجهی در استفاده کارآمد و مؤثر وجود خواهد داشت. این به طور بالقوه می تواند منجر به افزایش هزینه های پشتیبانی شود و خطر اعتبار برای هویت شرکتی محصول ایجاد کند. به هر حال، مستندسازی یک روش ارتباطی است. اطمینان از اینکه ارتباطات در یک چارچوب قابل مدیریت و قابل دسترسی محصور شده و در عین حال مرتبط با نسخه سازی مناسب است، بنابراین، اطمینان از برقراری ارتباط برای موفقیت است.
در زمان نگارش این مقاله، چارچوب Rucio برای تامین انرژی مورد نیاز آزمایش‌های ATLAS و CMS در LHC مورد استفاده قرار گرفته است. همچنین برای حمایت از نیازهای جوامع علمی مختلف فراتر از LHC، مانند اخترفیزیک استفاده می شود. بنابراین لازم است اسناد تا حد امکان مرتبط و در دسترس باشند. با کمک این پروژه، CERN می‌خواهد کاربران نهایی Rucio را قادر سازد تا ضمن استفاده از چارچوب، با ارائه یک نمای متمرکز برای دسترسی به تمام اسناد مربوطه، تجربه‌ای یکپارچه داشته باشند.
وضعیت فعلی: از امروز، اسناد کاربر در مکان‌های مختلف پخش شده است و در قالب‌های متعددی از جمله مقالات علمی، readthedocs.io با منبع در کد، Google Drive، GitHub، DockerHub یا Wikis است. منابع متعدد مشکلاتی را با ردیابی نسخه ها و صحت اسناد معرفی می کنند. علاوه بر این، یک مدل غیرمتمرکز اسناد، موانع قابل توجهی در جهت یابی و نمایان شدن اطلاعات مربوطه برای یک مورد خاص ایجاد می کند. به‌ویژه در مورد ویکی‌ها، اطلاعات ارائه‌شده برای یک آزمایش خاص می‌تواند به خوبی برای نمونه‌های دیگری که در منابع مشابه/دیگر هستند نیز قابل استفاده باشد. با این حال به دلیل عدم تثبیت و پیوندهای مناسب، این اطلاعات غیرفعال است و به طور بالقوه مورد استفاده قرار نمی گیرد.
چرا اسناد کاربر پیشنهادی شما نسبت به سند فعلی بهبود یافته است؟ با توجه به مشکل چند وجهی، مدل ارائه شده در زیر موانع را با ناوبری، نسخه‌سازی، ردیابی و نمایان کردن اسناد به شرح زیر حذف می‌کند:
بازسازی اسناد با هدف ساده‌سازی تلاش‌های صرف شده در مسیریابی برای کاربر نهایی است. او در حین جستجوی اطلاعات نیازی به پایین رفتن از سوراخ های خرگوش ندارد، زیرا آنها به دلیل سادگی دسته بندی یا برچسب گذاری می شوند. از منظر اداری، نسخه‌سازی و ردیابی آسان می‌شود، زیرا تجدید ساختار آزادی دسته‌بندی بر اساس نیاز را ارائه می‌دهد. متمرکز کردن تمام اسناد بازسازی شده برای اطمینان از اینکه همه اطلاعات برای کاربر قابل مشاهده است بدون نیاز به مراجعه به چندین منبع است.
تجزیه و تحلیل: پس از مطالعه مختصر الزامات و گفتگو با تیم مربی، استنباط من از وضعیت فعلی مستندات Rucio به شرح زیر است:
شش منبع اصلی اسناد وجود دارد: - پیوند Google Drive: https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7
Readthedocs ارائه شده توسط Sphinx با منبع در کد پیوند به کد: https://github.com/rucio/rucio پیوند به ReadtheDocs: https://rucio.readthedocs.io/en/latest/
لینک DockerHub: https://hub.docker.com/u/rucio
لینک GitHub: https://github.com/rucio/rucio
پیوند ویکی: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing
لینک مقالات علمی: https://arxiv.org/abs/1902.09857
اسناد در سراسر این منابع در قالب های مختلف است. به عنوان مثال، Google Drive دارای اسنادی به شکل اسلایدها و اسناد است، GitHub دارای فایل‌هایی است که عمدتاً به زبان نشانه‌گذاری reStructuredText و غیره هستند. کمبود نسخه‌سازی و ردیابی وجود دارد که منجر به انتشار اطلاعات اضافی در چندین منبع می‌شود. هیچ یکنواختی در برچسب گذاری/رده بندی اطلاعات وجود ندارد. بنابراین تجربه و تخصص قبلی در حین جستجو الزامی است.
با توجه به فرمت‌ها و منابع بی‌شمار، انتظار می‌رود که اطلاعات را بازسازی کرده و با استفاده از mkdocs متمرکز کنید. برای درک بهتر از ابزارها، تحقیق کرده و با کاربرد آنها آشنا شده ام.
حکم: اسناد موجود بدون ساختار و پراکنده و بدون پیوند مناسب است. همچنین فاقد تمرکز و یکنواختی در قالب بندی است. این باعث می شود که کاربران مجبور شوند تلاش بیشتری برای جستجو انجام دهند. چنین شکاف‌هایی همچنین فشار غیرضروری را بر مدیران/نگهبانان/سرنخ‌ها وارد می‌کند که به همین دلیل حفظ رویکرد جامعه محور برای نگهداری و به‌روزرسانی اسناد دشوار می‌شود. تجربه کاربر و مشارکت کننده به طور قابل توجهی تنزل یافته است و تکرار خواهد شد
ساختار اسناد پیشنهادی: پس از تجزیه و تحلیل کامل نیازمندی‌ها، تصمیم گرفتم از طریق یک مدل بازسازی‌شده از اسناد، به نقاط درد اصلی بپردازم.
مدل بازسازی شده در ماکت ضمیمه شده در زیر نشان داده شده است و هر بخش از اسناد را در 7 دسته زیر دسته بندی می کند:
- در باره
- شروع شدن
- مفاهیم
- رابط های روسیو
- وظایف
- آموزش ها
- دانش پیشرفته
البته، پیشرفت هایی مانند افزودن پیوندهایی وجود دارد که می خواهم در پایان این برنامه روی آنها کار کنم. با بیش از 1000 کاربر فعال که به 500 پتابایت داده در Rucio دسترسی دارند، بازسازی پیشنهادی اسناد آن باید بتواند به طور قابل توجهی نیاز کاربران به توسل به لیست پستی پشتیبانی را کاهش دهد. هدف این است که تجربه کاربری بهتری با کاهش تعداد کلیک‌ها و با نمای آسان اسناد از طریق طبقه‌بندی و برچسب‌گذاری داشته باشید. همه چیزهایی که باید از منظر کاربر/عملیات/ پرسنل مدیر دانست، با 3 کلیک یا کمتر در دسترس خواهد بود.
پیوند ماکت آپ: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)
اهداف پروژه: - تجزیه و تحلیل و هرس اطلاعات اضافی موجود از منابع مختلف. یعنی هر قطعه اطلاعاتی باید یک منبع حقیقت داشته باشد. - بازسازی با برچسب‌گذاری و دسته‌بندی اسناد موجود به بخش‌های مختلف - انتقال اسناد بازسازی‌شده به یک نمای متمرکز بر اساس mkdocs - اسنادی را که به دلیل محدودیت‌های قالب فایل نمی‌توانند منتقل شوند - تغییر ساختار مبتنی بر جامعه را تنظیم کنید تا اطمینان حاصل شود که هرگونه مفقودی وجود ندارد. شکاف ها پر می شوند - از نظر پیوندها، به روز رسانی اطلاعات یا تصحیح خطاها.
پایه‌های اصلی این سیستم در حال حاضر وجود دارد، با این حال، مدل من با تنظیم دستورالعمل‌های مناسب برای مشارکت و حکمرانی با مستندات مناسب، سیستم موجود را بهبود می‌بخشد. علاوه بر این، من تصور می کنم که تخته های پروژه GitHub را برای ردیابی مسائل و سلامت کلی پروژه ترکیب کنم.
جدول زمانی: - قبل از 16 آگوست --> با نسخه های فعلی مستندات و Rucio آشنا شوم --> تکنیک های جدید و مهارت های نوشتاری فنی را بیاموزم که در طول مدت پروژه مفید خواهند بود --> در صورت وجود، در مورد مسائل مستندسازی که گزارش شده است مشارکت داشته باشم. در GitHub
پیوند با جامعه (17 اوت - 13 سپتامبر) --> یک کانال ارتباطی و زمان ایجاد کنید تا تفاوت مناطق زمانی را محاسبه کنید (پونا 3 ساعت و 30 دقیقه جلوتر است) --> نقاط دردناک اصلی که باید در جهت اصلاح اهداف شناسایی شوند - -> با شرکت در مکالمات، درباره جامعه، سازمان و چارچوب بیشتر بیاموزید. --> ارزیابی ساختار مستندات پیشنهادی با مربیان و سایر اعضای کلیدی سازمان برای دوام و امکان سنجی اجرا. --> نهایی شدن ویژگی های پیشنهادی و هرگونه اصلاح دیگری که ممکن است نیاز باشد در اسناد موجود انجام شود.
دوره مستندسازی (14 سپتامبر - 30 نوامبر) بر اساس قالب پیشنهادی که در اینجا فرموله کردم، نقاط عطف اصلی را که قصد دارم در طول دوره مستندسازی به دست بیاورم، ارائه کرده ام.
--> نقطه عطف شماره 1: طبقه بندی و برچسب گذاری ETC: 28 سپتامبر 2020 جذب اسناد موجود و برچسب گذاری آنها فرآیند بازسازی و هرس را بسیار ساده می کند.
--> نقطه عطف شماره 2: تجزیه و تحلیل، هرس و بازسازی ETC: 19 اکتبر 2020 اسنادی که در طول نقطه عطف شماره 1 طبقه بندی شده اند برای موارد تکراری + منابع اطلاعات اضافی تجزیه و تحلیل می شوند. همانطور که در اطلاعات پروژه بیان شد، ما یک منبع حقیقت را برای تمام اطلاعات موجود هدف قرار می دهیم.
--> نقطه عطف شماره 3: متمرکز کردن و قالب بندی مجدد: ETC: 9 نوامبر 2020 هنگامی که اسناد به درستی هرس و بازسازی شد، ابتدا می خواهم آن را دوباره قالب بندی کنم. با توجه به منابع مختلف، قالب ها متفاوت هستند و ابتدا باید به یک قالب مناسب تبدیل شوند. پس از انجام این کار، فرآیند متمرکز سازی آسان تر می شود.
--> نقطه عطف شماره 4: راه اندازی تابلوهای ردیابی + اسناد و مدارک در مورد حاکمیت/ مشارکت ها و غیره: 23 نوامبر 2020 این مرحله برای اطمینان از اینکه پس از اتمام پروژه، مستندات همچنان به روز می مانند. تعیین رهنمودها و راه اندازی هیئت مدیره پروژه، بار اعضای اداری را برای درخواست مشارکت های جامعه و پیگیری موثر آنها کاهش می دهد.
--> ارزیابی پروژه (30 نوامبر - 5 دسامبر) ارائه گزارش پروژه و ارزیابی مربیانم گزارشی از تجربه خود به عنوان یک شرکت کننده در Season of Docs بنویسید و ارسال کنید.
چرا این پروژه؟ من بر این باور بودم که تکمیل کد با مستندات به خوبی نوشته شده و نسخه‌بندی شده تنها راه برای فعال کردن پذیرش بیشتر و استفاده بهتر است. من شخصاً مجذوب روشی شده‌ام که سرن در تحقیقات پیشرفته در زمینه‌های مختلف فیزیک پیشگام بوده است. با توجه به مقیاس اطلاعات پردازش، انتقال و تولید شده در طول چنین آزمایش‌هایی، من همیشه درگیر این بودم که چگونه داده‌ها برای مرجع و استفاده آتی در سازمان مدیریت می‌شوند. کمک به بهبود اسناد برای چارچوبی که به برخی از تحقیقات و اکتشافات علمی شگفت انگیز کمک می کند باعث افتخار خواهد بود.
چرا من شخص مناسبی برای این پروژه هستم؟ علاوه بر رعایت پیش نیازها، مطمئن هستم که فرد مناسبی برای این پروژه خواهم بود زیرا:
من در حال حاضر در حال کار بر روی اصلاح اسناد موجود برای Kubernetes هستم. این مشارکت‌ها منجر به ثبت نام من به عنوان Release Docs Shadow برای چرخه انتشار 1.19 Kubernetes شده است که در آن به طور مؤثری در حفظ و ارتقای اسناد برای ویژگی‌های جدیدی که در طول انتشار اضافه می‌شوند کمک می‌کنم. من معتقدم که مستندات خوب ستون فقرات یک محصول/خدمت عالی است. چه رویه ای یا فنی باشد، اطلاعاتی که به خوبی نوشته شده، مختصر و به راحتی قابل دسترسی باشد، انگیزه ای برای پذیرش و کمک به استفاده بهتر خواهد بود. با کارکردن با سیستم‌های توزیع‌شده مبتنی بر داده در تمام طول زندگی حرفه‌ای‌ام، معتقدم که در بهترین موقعیت برای درک پیچیدگی‌های الزامات مربوط به مستندات چنین سیستم‌هایی هستم. من که خود کاربر نهایی بوده‌ام، با اشکالات مستندات نادرست/نوشته شده آشنا هستم و مراقب خواهم بود که در طول بازسازی، آنها را در نظر بگیرم.