این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.
خلاصه پروژه
- سازمان منبع باز:
- بنیاد محاسبات بومی ابری (CNCF)
- نویسنده فنی:
- شریتی
- نام پروژه:
- بهبود اسناد SMI و مش های خدمات مرتبط
- طول پروژه:
- طول استاندارد (3 ماه)
شرح پروژه
فناوری Service Mesh اساساً با هدف ارائه ارزش به تعداد فزاینده خدمات، از طریق رسیدگی به تمام نیازهای امنیتی، مدیریتی و نظارتی شما انجام می شود. Service Mesh Interface (SMI) مجموعه‌ای از APIها را برای رایج‌ترین موارد استفاده از مش (سیاست ترافیک، تله متری و جابجایی) تعریف می‌کند و سازگاری بین مش‌های سرویس را امکان‌پذیر می‌کند، که لایه‌های زیرساخت اختصاصی برای مدیریت ارتباط سرویس به سرویس در یک محیط میکروسرویس ها استانداردسازی این رابط‌ها یک تجربه کاربر نهایی پیشرفته را فراهم می‌کند و بنابراین، یک هدف آینده برای SMI و شبکه‌های خدمات مرتبط است.
وضعیت فعلی:
راهنمای کاربر: SMI یک پروژه جعبه ایمنی نسبتاً جدید است که در آوریل 2020 به CNCF اهدا شد. در نتیجه، پروژه فاقد مستندات کاربر نهایی است. Meshery یک صفحه مدیریت خدمات با معیار عملکرد برای انواع خدماتی است که پذیرش، پیکربندی، عملیات و مدیریت عملکرد مش های مختلف سرویس را تسهیل می کند و مجموعه و نمایش معیارهای برنامه های کاربردی را در بالای هر سرویس مشی اجرا می کند. بنابراین، من می خواهم با راهنمای مشری شروع کنم، که به عنوان نقطه شروعی برای کل جامعه کاربران SMI عمل خواهد کرد.
آموزش های کاربر: در میان پلتفرم های SMI موجود: برنامه نمونه، Learn Layer5، در حال حاضر به عنوان یک دستگاه یادگیری برای SMI و به عنوان برنامه نمونه برای انجام اعتبار سنجی مشخصات SMI عمل می کند. اما در غیر این صورت، پروژه های SMI به طور کامل فاقد آموزش های کاربر نهایی هستند. به دلیل ماهیت بسیار فنی پروژه ها یک مانع جدی است. Meshery برنامه عالی برای نمایش مزایا و استفاده از SMI و مش های خدمات مرتبط است، به همین دلیل است که من از آن به عنوان ابزار پایه برای نمایش ویژگی های SMI استفاده خواهم کرد.
اسناد API: در حال حاضر وجود ندارد. SMI و پروژه های مختلف مرتبط، نقاط پایانی API خود را بر روی یک پلت فرم تعریف می کنند. به عنوان مثال، Meshery نقاط پایانی خود را در server.go تعریف کرده است (https://github.com/layer5io/meshery/blob/master/router/server.go)، اما آنها به خوبی اظهار نظر یا مستندسازی خارجی ندارند. این را می توان با مستندات معنی دار API حل کرد و با افزودن روش هایی برای کاربران برای آزمایش نقاط پایانی آن و پیش نمایش ویژگی های آن، بهبود یافت.
تحلیل:
آموزش های کاربری ایجاد شده است تا به کاربر اجازه دهد تا نرم افزار را درگیر کند و آزمایشی را انجام دهد. آنها باید تعاملی و از نظر زیبایی شناسی جذاب باشند تا توجه کاربر را به خود جلب کنند و مهمتر از همه، استفاده آسان باشد.
با این حال، برای نوشتن یا میزبانی راهنماهای کاربر، قالبی بالغ‌تر توصیه می‌شود، زیرا راهنمای کاربر اغلب به عنوان راهنمای مرجع یا مکانی برای رفع سریع مشکلات است. آنها به جای تعاملی بودن، باید ساختار خوبی داشته باشند و بر بهبود وضوح، انسجام و جریان کاربر خوب تمرکز کنند.
یک راه حل ممکن برای این امر ایجاد آموزش های کاربر جداگانه با استفاده از Google Codelabs و یک راهنمای کاربر مستقل با کمک Jekyll و در نهایت ادغام آنها به همراه اسناد API برای ارائه یک تجربه کامل به کاربر نهایی و همکاران آینده است. .
مخاطب هدف: پروژه‌های SMI روش‌های استقرار و عملیاتی، محیط‌های یادگیری و معیارهای عملکرد را برای همه پروژه‌های تحت آن ارائه می‌کنند. هم به افراد و هم به سازمان ها پاسخ می دهد.
راهنماهای کاربر: من کاربران مبتدی را هدف قرار خواهم داد، بدون هیچ پیش فرضی مبنی بر دانش IT از قبل موجود در پایان کاربر. هدف: کاربران مبتدی دلیل: عمدتاً به عنوان یک راهنمای مرجع گسترده استفاده می شود که باید با گذشت زمان به روز شود. این شامل توضیحات عمیق و نکات مفیدی است تا مطمئن شود کاربر تمام اطلاعات مورد نیاز برای راه اندازی و کار با یک سرویس مش را دارد. این راهنما با افزودن فیلم‌ها، تصاویر، اسکرین‌شات‌ها و تصاویر GIF، در هر کجا که لازم باشد، جذاب‌تر و کاربرپسندتر می‌شود.
آموزش های کاربر: هدف: کاربران مبتدی دلیل: تمرکز بر این خواهد بود که آموزش ها جذاب و از نظر زیبایی شناسی جذاب باشد تا توجه کاربر را به خود جلب کند و امکان اجرای آزمایشی نرم افزار را فراهم کند، که منجر به درک بهتر رابط مش سرویس می شود.
مستندات نقطه پایانی API: هدف: کاربران پیشرفته دلیل: این بخش بر استفاده از ویژگی های پیچیده تر سرویس مش تمرکز دارد که بیشتر به نفع کاربران پیشرفته با سطح دانش پایه IT است. کاربران پیشرفته به دنبال آموزش های مختصر هستند که در صورت نیاز می توانند به عنوان راهنمای مرجع نیز مورد استفاده قرار گیرند. مستندات Endpoint باید به گونه‌ای نوشته شود که به‌روزرسانی آن آسان باشد، بدون اینکه دقت یا سازگاری آن به خطر بیفتد. ترجیحاً این باید یک فرآیند خودکار باشد.
منابع: راهنمای کاربر: Codelab توسعه دهندگان گوگل - برای ساختن آموزش های تعاملی و جامع کاربر نهایی استفاده می شود. مزایا: - می تواند آموزش جعبه شنی تولید کند. - رویکرد عملی دارد. - با استفاده از Google Docs نوشته شده و از متن Markdown پشتیبانی می کند. - قابل نظارت با استفاده از Google Analytics - مشاهده آسان ترافیک کاربر. - استفاده آسان. آموزش های زیبایی شناسی را تولید می کند که به کاربر امکان می دهد مستقیماً بدون سرمایه گذاری مستقیم با نرم افزار درگیر شود.
Google Codelabs را می توان با استفاده از پروژه CLaaT (Codelabs as a Thing) ارتقا داد و به راحتی مستقر کرد - این برنامه ای است که ابزار خط فرمانی را ارائه می دهد که برای تبدیل آموزش های نوشته شده در Google Doc با استفاده از Markdown به قالب کدلب (HTML) استفاده می شود.
راهنمای کاربر: Jekyll - اسناد موجود برای meshery.io، که در اینجا یافت می شود، در Jekyll میزبانی می شود و از موضوع Docsy Jekyll استفاده می کند. از Markdown، مایع، HTML و CSS برای تولید وب‌سایت‌های آماده میزبان، ثابت و اجرا در محیط توسعه Ruby استفاده می‌کند. مزایا: - می تواند سایت ها را مستقیماً از مخازن GitHub میزبانی کند. - این یک پروژه با پشتیبانی خوب با یک جامعه بسیار فعال است - راهنماهای کاربری و پیشرفت‌ها را می‌توان به سادگی به اسناد SMI و Meshery موجود اضافه کرد، بدون اینکه مجبور باشید برای مهاجرت به پلتفرم دیگری زحمت بکشید.
اسناد API: Swagger (به طور متناوب Swaggo) برای ایجاد اسناد API برای SMI و Meshery استفاده خواهد شد. این یک راه حل زیبا برای نوشتن اسناد API است. مزایا: - مستندسازی از طراحی API شما: اطمینان حاصل می‌کند که اسناد شما با تکامل API شما به‌روز می‌مانند. - مستندات از طراحی API شما: می تواند به طور خودکار از تعاریف API تولید شود. - حفظ نسخه های مستند چندگانه - طراحی های API سفارشی شده
اهداف پروژه: - برای ایجاد آموزش های تعاملی کاربر نهایی برای SMI و شبکه های خدمات مرتبط با استفاده از Meshery به عنوان یک ابزار، از Google Developer Codelabs استفاده کنید. - با استفاده از Jekyll برای مش های سرویس، یک راهنمای کاربر نهایی ایجاد کنید. - از Swagger برای تولید اسناد نقطه پایانی API برای SMI استفاده کنید. - جامعه پروژه را به گونه‌ای هدایت کنید که کاربران یا توسعه‌دهندگان آینده و فعلی بتوانند به راحتی تحت هدایت و نظارت انجمن SMI به اضافه کردن آن ادامه دهند.
جدول زمانی: جدول زمانی پیشنهادی را می‌توانید در اینجا پیدا کنید: https://docs.google.com/document/d/1If2mtBdWZer4qrh66NfXOWBx_3-tiA09jnoPMqy2lqs/edit#bookmark=kix.j1b6m64eubsl
ساختار: ساختار پیشنهادی برای راهنمای کاربر را می‌توانید در اینجا بیابید: https://docs.google.com/document/d/1A3YYAMUte06MojNWo8hdF4KZbvr-qVaaA2myzWeshHQ/edit?usp=sharing
چرا این پروژه؟ جامعه مش خدمات با سرعت رعد و برق سریع در حال گسترش است که با ادغام اخیر آن به عنوان یک پروژه sandbox در CNCF فعال شده است. با این حال، این پروژه شاهد کمبود جدی مستندات، هم برای کاربران نهایی و هم برای توسعه دهندگان است. من در گذشته با سرویس‌های مختلفی از جمله linkerD با برنامه EmojiVoto، Istio با برنامه bookinfo و کنسول Hashicorp بازی کرده‌ام. من تقسیم ترافیک SMI را نیز امتحان کرده‌ام و قوانین اعتبارسنجی مختلفی را در پیکربندی مش سرویس خود پیاده‌سازی کرده‌ام. فرآیند یادگیری بسیار جذاب است اما بسیار فنی است و می تواند برای کاربران جدید و همچنین توسعه دهندگانی که به دنبال برداشتن اولین گام های خود در جامعه سرویس مش یا استفاده از مش های سرویس برای پروژه های شخصی یا حرفه ای خود هستند، به تعویق بیفتد. من می‌خواهم این شکاف را پر کنم که تنها با راهنماها و آموزش‌های کارآمد و مستند قابل انجام است.