این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.
خلاصه پروژه
- سازمان منبع باز:
- gRPC-Gateway
- نویسنده فنی:
- ایامرجیو
- نام پروژه:
- بازسازی سایت اسناد موجود در gRPC-Gateway
- طول پروژه:
- طول استاندارد (3 ماه)
شرح پروژه
چکیده:
سایت اسناد کاربر برای کمک به کاربران نهایی برای استفاده از یک محصول یا خدمات طراحی شده است. سایت Docs خوب کاربر بسیار مهم است زیرا راهی را برای کاربران فراهم می کند تا نحوه استفاده از نرم افزار، ویژگی ها، نکات، ترفندهای آن را بیاموزند و همچنین مشکلات رایجی که هنگام استفاده از نرم افزار با آن مواجه می شوند را حل کنند. همچنین هزینه پشتیبانی را کاهش می دهد و بخشی از هویت شرکتی محصول است. سایت خوب user docs نشانه سالم بودن محصول تیم توسعه دهنده است. بدون سایت اسناد کاربر خوب، کاربر ممکن است نداند که چگونه کارهای فوق را به طور موثر و کارآمد انجام دهد. سایت Docs کاربر می تواند نقشی اساسی در تضمین موفقیت یک محصول داشته باشد زیرا ارتباطات عالی همیشه در قلب هر کسب و کار یا محصولی وجود دارد و خواهد بود و اسناد عالی فقط آن ارتباط را گرفته و آن را در یک چارچوب قابل مدیریت قرار می دهد که همه می توانند برای موفقیت به آن دسترسی داشته باشند.
در زمان نگارش این مقاله، مخزن gRPC-Gateway تقریباً 1200 بار فورک شده است و 184 نفر در این مخزن مشارکت داشته اند که نشان می دهد افراد زیادی در سراسر جهان از gRPC-Gateway استفاده می کنند و ممکن است بخواهند کاربر آن را بخوانند. مستنداتی برای راهنمایی در مورد نحوه استفاده از gRPC-Gateway. با این حال، سایت اسناد و مدارک کاربر gRPC-Gateway در حال حاضر قدیمی و ناقص است و انجمن gRPC-Gateway می‌خواهد از این پروژه برای بازسازی سایت اسناد موجود استفاده کند تا سایت اسناد خود را بهبود بخشد تا کاربران نهایی بتوانند تجربه‌ای یکپارچه در هنگام استفاده از آن داشته باشند. gRPC-Gateway.
وضعیت فعلی:
در حال حاضر، سایت اسناد gRPC-Gateway دو مشکل عمده دارد:
• اولین مشکل وب سایت Docs بد و قدیمی است که استایل و ساختار سایت و تم مورد استفاده منسوخ، ناقص، سخت برای پیمایش یا یافتن اطلاعات است، بسیاری از ویژگی های وب سایت Docs خوب را پوشش نمی دهد. بازسازی سایت Docs موجود در gRPC-Gateway شامل استایل سازی وب سایت، افزودن ویژگی هایی مانند جستجوی اسناد و غیره، بهبود رابط کاربری وب سایت، سازماندهی آموزش ها و مثال ها در یک نوار کناری مناسب و به روز رسانی فلوچارت ها و تصاویر موجود با طراحی یک مورد جدید و غیره خواهد بود. این هدف اصلی من خواهد بود و کار من بیشتر بر اساس استایل و بازسازی سایت Docs موجود خواهد بود.
• مشکل دوم، نیاز به اصلاح مستندات موجود، آموزش‌ها و مثال‌ها و غیره از gRPC-Gateway است که می‌توان با حذف اشتباهات تایپی و گرامری در بین فایل‌ها، ترازبندی مناسب قطعه‌های Go و بازسازی قطعه‌های Go بر اساس Gofmt انجام داد. فرمت ها همچنین، اگر چنین است، می‌توانیم مستندات، آموزش‌ها و مثال‌های بیشتری را در صورت نیاز اضافه کنیم یا می‌توانیم پس از بازسازی مجدد فایل‌های موجود را دوباره استفاده کنیم. این هدف ثانویه من است و این کار را پس از تکمیل هدف اصلی خود یعنی طراحی و بازسازی سایت Docs فعلی انجام خواهم داد.
چرا سایت DOCS پیشنهادی من نسبت به سایت فعلی بهبود یافته است؟
وب‌سایت اسناد کاربر پیشنهادی برای بهبود و اطمینان از کارایی، سازگاری و آرامش خاطر برای کاربر نهایی ساخته خواهد شد. ظاهر و رابط کاربری بهتری با بخش‌ها و ویژگی‌های به‌خوبی سبک‌سازی‌شده و حاوی راهنماهای نوشته شده و فلوچارت‌ها و تصاویر مرتبط با آن می‌دهد.
مستندات gRPC-Gateway شرح خوبی از روش و مثال ارائه می دهد. اما هنوز هم از تم قدیمی جکیل استفاده می کند و در روزهای امروزی ما تم های جکیل SSG (Static Site Generator) بهتری داریم. همچنین با افزودن نمونه ها و آموزش های جدید و به روز رسانی و بازنویسی مطالب قبلی، نیاز به بازسازی صفحات و مفیدتر ساختن آن برای کاربران وجود دارد.
ساختار و نقشه راه اهداف و ایده های پیشنهادی:
هدف اولیه این پروژه:-
اهداف و ایده های فوق را می توان به روش های زیر اجرا کرد:
تغییر تم فعلی جکیل به تم بهتر و قوی. دلیل استفاده مجدد از تم‌های Jekyll این است که برای نگهبان‌ها مشارکت و درک گردش کار پروژه آسان خواهد بود، زیرا آنها قبلاً از چارچوب و موضوع Jekyll موجود که شبیه به تم جدید Jekyll است آگاه هستند.
پس از مرور مضامین مختلف Jekyll در سراسر اینترنت، این مجموعه تم https://idratherbewriting.com/documentation-theme-jekyll/ را برای سایت اسناد gRPC-Gateway به دلیل ویژگی زیر بهترین انتخاب کردم:
• Markdown: - به طوری که نویسندگان فنی نگران نصب نباشند. آنها می توانند به سادگی در فایل .md بنویسند. هر کسی می تواند روی دکمه ویرایش نشان داده شده در وب سایت (ویژگی جدید) کلیک کند و برای بهتر کردن صفحه (ویرایش/پیشنهاد تغییرات برای صفحه در GitHub) مشارکت کند. این کار باعث می شود که کاربران به افزودن محتوای جدید یا ویرایش محتوا برای بهبود آن بپردازند.
• جستجوی اسناد: - کاربر باید یک کادر جستجو داشته باشد تا بتواند به راحتی و به سرعت مطالب مرتبط را پیدا کند.
• بخش نظرات: - کاربر ممکن است این گزینه را داشته باشد که نظرات خود را در مورد پست ها و آموزش ها به اشتراک بگذارد. آنها می توانند نظرات دیگران را در مورد اسناد پروژه بخوانند.
• یادداشت ها و وبلاگ های انتشار جدید: - وب سایت باید با پست های وبلاگ جدید و اخبار مربوط به توسعه فعلی و نقشه راه به روز شود. بنابراین نوع وبلاگ نویسی باید در صفحه فرود وجود داشته باشد.
• توسعه سریع: - اکثر چارچوب های SSG (Static Site Generator) در سرور در حال اجرا هستند و تغییرات در فایل بلافاصله در UI منعکس می شود. همچنین استقرار و فرآیند ساخت باید آسان باشد. در آینده، اگر بخواهیم چارچوب را تغییر دهیم، استفاده می کنیم. سپس باید آسان باشد. اکثر فریم‌ورک‌ها از نوشتن Markdown پشتیبانی می‌کنند، بنابراین فقط جابجایی فایل‌های md و تغییرات کمی کافی است.
در اینجا من صفحات وب سایت موجود را به بخش ها و صفحات وب سایت جدید تقسیم می کنم:
• صفحه فرود:-
صفحه فرود باید به ویژگی های اصلی gRPC-Gateway اشاره کند.
- شروع به کار با gRPC-Gateway (به راهنمای کاربر تغییر مسیر دهید)
- دستورالعمل های نصب ساده (فرمان های مختصر)
- چرا از gRPC-Gateway استفاده کنید؟
- پروژه با استفاده از gRPC-Gateway
بنابراین ایده اصلی به جای نوشتن توضیحات طولانی، نمایش نکات اصلی در صفحه فرود و ارائه لینک برای رفتن به جزئیات است.
• صفحه راهنمای کاربر gRPC-Gateway:-
- راهنمای نصب.
- شروع سریع با gRPC-Gateway.
• صفحه راهنمای برنامه نویس gRPC-Gateway:-
راهنمای توسعه، راهنمای مشارکت، راه‌اندازی Git، کد رفتار، تنظیم اسناد، گردش کار توسعه و غیره به صفحات مشابه در داخل اشاره می‌کنند. بنابراین به بازسازی و تنظیم مجدد همه فایل ها نیاز است. صفحه توسعه اصلی باید شامل همه این صفحات باشد و در هر مرحله لینک ایجاد می شود.
• درباره صفحه gRPC-Gateway:-
فهرست همه مشارکت‌کنندگان باید در بخش‌های تیم وجود داشته باشد پیوندهای سریع و یادداشت‌های انتشار، آخرین وبلاگ‌ها اضافه می‌شوند تا کاربر را درگیر کند تا آنها را در مورد اخبار gRPC-Gateway فعلی بخواند.
• وبلاگ ها، یادداشت های انتشار و صفحه آموزش:-
من فکر می کنم که وب سایت باید یک گزینه وبلاگ نویسی داشته باشد. بنابراین اخبار و انتشارات را می توان به راحتی در میان گذاشت. صفحه آموزش شامل چند سخنرانی و مقاله معروف است که APIها و مفاهیم gRPC-Gateway را روشن می کند. مشارکت کنندگان می توانند پیوندهای آموزشی خود را در صفحه آموزش اضافه کنند.
پس از اتمام کار بالا همان تغییرات را در شاخه v2 و حتی با شاخه اصلی gRPC-Gateway به روز رسانی کنید.
هدف ثانویه این پروژه:
تغییرات دیگری باید انجام شود تا اسناد gRPC-Gateway قوی تر و قابل خواندن تر باشد:
• رفع اشکالات گرامری، تایپی و سازماندهی و تراز کردن لینک ها و پست های سایت در تمامی فایل های موجود gRPC-Gateway.
• افزودن مستندات و محتوای بیشتر در صورت نیاز در gRPC-Gateway زیرا اکثر ویژگی ها دارای اسناد بسیار کوتاه هستند مانند بخش Documentation سایت در مورد AWS، Background and Usage و غیره.
• Refactoring Go snippets gRPC-Gateway مطابق با فرمت های Gofmt
پس از اتمام کار بالا همان تغییرات را در شاخه v2 و حتی با شاخه اصلی gRPC-Gateway به روز رسانی کنید.
چرا من شخص مناسب برای این پروژه هستم:
من معتقدم که من شخص مناسبی برای این پروژه هستم زیرا:
• من تجربه قبلی در بهبود مستندات سازمان ها را دارم و می توانم از هر سیستم کنترل نسخه استفاده کنم، بنابراین انجام دستورات در GitHub مشکلی نخواهد داشت. • علاوه بر این، چیزی که من را تحریک می کند کار بر روی پروژه هایی است که برای مردم ارزش ایجاد می کند. من معتقدم که اگر می خواهید کسی کاری را به کارآمدترین شکل ممکن انجام دهد، آن را مستند می کنید. با مستندسازی فرآیندهای خود، کارایی، ثبات و آرامش خاطر را برای هر کسی که درگیر است تضمین می کنید. • من با گردش کار و پایگاه کد gRPC-Gateway آشنا هستم زیرا از دو ماه گذشته در gRPC-Gateway مشارکت داشتم و 11 PR ادغام شدم.