این صفحه حاوی جزئیات یک پروژه نگارش فنی است که برای فصل اسناد Google پذیرفته شده است.
خلاصه ی پروژه
- سازمان منبع باز:
- الکترون
- نویسنده فنی:
- آقای گلد
- نام پروژه:
- جریان آموزش الکترون
- طول پروژه:
- طول استاندارد (3 ماه)
شرح پروژه
خلاصه ی پروژه
Electron یکی از محبوب‌ترین ابزارها برای ساخت برنامه‌های دسکتاپ چند پلتفرمی با جاوا اسکریپت، HTML و CSS است. مجموعه ای از برنامه های ساخته شده بر روی Electron تقریباً 900 ورودی دارد و این لیست به طور مداوم در حال افزایش است. برخی از محبوب ترین ابزارهای توسعه دهنده مانند Visual Studio Code، Atom، Postman، Slack، GitKraken بر روی Electron ساخته شده اند.
محبوبیت Electron در منحنی یادگیری ساده و آستانه ورودی پایین آن نهفته است - هر کسی که جاوا اسکریپت، HTML، پشته CSS را می‌داند می‌تواند برنامه کاربردی خود را بسازد. نرخ‌های رشد کلی، نیاز به ایجاد آموزش‌ها و راهنماهایی را که درک و استفاده آسان هستند، دیکته می‌کند.
هدف این پروژه جلب اعتماد به سازندگان برنامه های کاربردی است که تازه با فریم ورک Electron آشنا شده اند و تجربه ای منسجم و کارآمد در توسعه برنامه های کاربردی Electron خود را از پایه به آنها ارائه دهد.
مسائل پروژه
در زیر لیستی از مهم ترین مسائل مربوط به مستندات آموزشی الکترون آمده است: 1. نقطه شروع نامشخص و اطلاعات مقدماتی غیر شهودی در مورد مراحل توسعه برنامه 2. اطلاعات پراکنده و اضافی مربوط به فرآیند توسعه برنامه 3. قطعات بهم ریخته "شروع به کار" دستورالعمل‌ها را بدون هیچ منبعی از حقیقت راهنمایی کنید
پیشنهاد پروژه
با توجه به هدف پروژه و مسائلی که در بالا ذکر شد، لیستی از پیشرفت های پیشنهادی در زیر آمده است: 1. راهنماهای موجود را به روز کنید. برای اینکه اولین قدم‌ها صاف و منسجم باشد، اسناد زیر باید با تغییر تدریجی از ساده به پیچیده‌تر به‌روزرسانی شوند: - محیط توسعه‌دهنده - نوشتن اولین برنامه الکترونیکی شما - افزودن ویژگی‌ها به برنامه شما (ایجاد یک صفحه خلاصه) - بسته‌بندی برنامه و توزیع 2. دایرکتوری مستندات را بازسازی کنید. برای نشان دادن به توسعه دهندگان جدید از آنچه برای شروع ضروری است و آنچه را که می توان به عنوان مراحل بعدی در نظر گرفت، صفحه اسناد باید دارای تقسیم بصری و متنی مراحل باشد تا اولین برنامه را با بیشترین سرعت ممکن زنده کند. بازسازی همچنین شامل راهنمایی در مورد مراحل بعدی احتمالی است. 3. سازماندهی و یکسان سازی اسناد توسعه برنامه. همه ویژگی‌ها باید مجموعه‌ای از دستورالعمل‌های یکپارچه در مورد نحوه نصب/فعال کردن آن، نحوه شروع سریع، نحوه کار با یک برنامه پس از اولین راه‌اندازی و نحوه توزیع آن داشته باشند. 4. مخزن electron-api-demos را در مستندات قرار دهید. مخزن electron-api-demos شامل مجموعه‌ای از مثال‌ها است که نشان می‌دهد چگونه می‌توان ویژگی‌ها را به برنامه Electron خود اضافه کرد. این اطلاعات باید در راهنمای افزودن ویژگی‌ها به برنامه شما گنجانده شود تا با یک منبع واحد از استراتژی محتوای حقیقت سازگار باشد. 5. نمونه های Electron Fiddle را در مستندات ادغام کنید. این مرحله برای توسعه دهندگان جدید آسان تر می کند تا بدون نیاز به تکرار مراحل به صورت دستی، ببینند یک قطعه کد خاص چگونه کار می کند. این ادغام شامل نوشتن نمونه کد برای آموزش های به روز شده و افزودن دکمه "راه اندازی در کمانچه" به بلوک های کد است.
جدول زمانی
دوره بررسی برنامه - با جامعه و افرادی که باید با آنها کار کنید آشنا شوید. راهنماهای مشارکت جامعه و بهترین شیوه ها را بیاموزید. اولین مشارکت ها را انجام دهید. پیوند جامعه - جامعه را کاوش کنید. وضعیت فعلی مستندات Electron را بررسی کنید. نقاط ضعف را شناسایی کنید. هفته 1 - با مربیان در نقاط عطف پروژه و موارد قابل تحویل هماهنگ شوید هفته 2 - محیط توسعه دهنده را بازبینی کنید و اولین صفحات برنامه الکترونیکی خود را بنویسید هفته 3 - معماری برنامه را اصلاح کنید، ویژگی ها را به برنامه، بسته بندی برنامه و صفحات توزیع اضافه کنید. ایجاد یک صفحه خلاصه با لیستی از ویژگی هایی که می توان به برنامه اضافه کرد. هفته 4 - بازسازی فهرست اسناد هفته 5 - آماده سازی الگویی از نحوه ادغام الکترون-api-دموها در مستندات اصلی هفته های 6 تا 7 - مهاجرت به مخزن electron-api-demos هفته 8 - الگویی از نحوه ادغام Electron Fiddle در مستندات اصلی تهیه کنید. اولین نمونه را بنویسید هفته 9 - 10 - ادغام Electron Fiddle در مستندات اصلی هفته 11 - نهایی شدن ساختار اسناد اصلی و صفحات پس از مهاجرت مخزن electron-api-demos و نمونه های Electron Fiddle هفته 12 - ارزیابی نتایج
تفصیل نقاط عطف
دوره بررسی برنامه قسمت اول این دوره به بررسی کانال های انجمن و کد منبع و تماس با افرادی که به پروژه اختصاص داده شده اند اختصاص خواهد یافت.
بخش دوم این دوره به بررسی فرهنگ مشارکت به طور کلی، بررسی راهنماهای مشارکت و بهترین شیوه ها اختصاص خواهد یافت. این زمان برای اولین مشارکت ها خواهد بود تا نحوه عملکرد جریان را ببینیم.
پیوند جامعه
این زمان به بررسی عمیق پوشه اسناد به همراه نقشه راه آن اختصاص خواهد یافت. بر اساس آن اطلاعات، شناسایی نقاط ضعف (مثلاً قسمت‌های ناقص یا گمشده) که قابل بهبود هستند، امکان‌پذیر خواهد بود. برای پر کردن شکاف‌ها، درخواست‌های کشش (در صورت امکان) ایجاد کنید.
هفته 1 - هفته 2
هفته اول به برقراری ارتباط با مربیان به منظور هماهنگی با نقاط عطف مورد انتظار و تحویل به موقع آنها اختصاص خواهد یافت.
هفته دوم درباره بازنگری در محیط توسعه دهنده و نوشتن صفحات اولین برنامه الکترونیکی شما خواهد بود. برای صفحه Developer Environment شامل بازنویسی نمای کلی و تصحیح می شود. برای صفحه Writing Your First Electron App شامل تبدیل صفحه به یک راهنمای گام به گام منسجم با نقطه شروع و پایان روشن، حذف اطلاعات اضافی (مانند دو بلوک کد مشابه در زیر توسعه Electron به طور خلاصه و امتحان کردن این مثال است. بخش).
موارد تحویلی: بازبینی شده، دستورالعمل‌های معرفی آسان در مورد نحوه شروع سریع با برنامه‌های Electron.
هفته 3
این هفته به موارد زیر اختصاص خواهد داشت: 1. بهبودهای صفحه معماری برنامه. این شامل موارد زیر است: - بازنویسی اطلاعات موجود در بخش فرآیندهای اصلی و رندر برای ساده‌تر و شهودی‌تر کردن آن برای خواننده‌ای که برای اولین بار انجام می‌شود - اضافه کردن نمایش بصری معماری، نحوه اتصال فرآیندها، نحوه ارتباط آنها و تفاوت اصلی آنها. نمونه هایی از تصاویر: یک، دو، سه (کیفیت پایین). 2. یکسان سازی اطلاعات در مورد تمام ویژگی هایی که می توانید به برنامه Electron خود اضافه کنید. این شامل بازنویسی راهنماها می‌شود تا مجموعه‌ای از دستورالعمل‌های یکپارچه در مورد نحوه نصب/فعال کردن یک ویژگی به همراه نمونه‌ای از نحوه عملکرد ویژگی داشته باشند. علاوه بر این، یک صفحه (خلاصه) جدید که تمام ویژگی های موجود برای استفاده را فهرست می کند ایجاد خواهد شد. دستورالعمل های یکپارچه ممکن است به صورت زیر باشد: - نمای کلی - مثال: - نمونه کد - نمونه تصویری (در صورت امکان)
- ساده سازی صفحه توزیع برنامه این شامل: الف. ادغام بسته بندی برنامه در راهنمای توزیع برنامه ب. تقسیم روش های توزیع به اتوماتیک و دستی ج. گرفتن الکترون فورج به عنوان نمونه ای از توزیع خودکار d. گرفتن اطلاعات در مورد asar از صفحه بسته بندی برنامه و توصیف کپی فایل های منبع و ایجاد آرشیو asar به عنوان نمونه هایی از توزیع دستی. #### هفته چهارم این هفته به بازسازی دایرکتوری مستندات اختصاص خواهد داشت. آن شامل:
1- تقسیم راهنماهای موجود حداقل به سه دسته: الف. شروع سریع ب. یادگیری اصول ج. مراحل پیشرفته
دسته شروع سریع شامل آموزش های اساسی (نصب، پیکربندی، توزیع) برای ایجاد یک سری راهنماهای ثابت است که به تازه واردان اجازه می دهد تا از ابتدا سریع شروع کنند. هر راهنما باید حاوی پیوندهایی به راهنماهای قبلی/ بعدی مجموعه باشد.
ساختار ممکن است به شکل زیر باشد: 1. پیش نیازها 2. نصب Electron 3. ایجاد یک برنامه کاربردی پایه 4. بسته بندی/توزیع برنامه
پس از تکمیل بخش Quickstart، کاربر اصول اولیه نحوه کار برنامه های Electron را می داند و یک برنامه Electron قابل توزیع کاملاً کارآمد خواهد داشت.
دسته یادگیری اصول اولیه شامل راهنماهایی با هدف تقویت دانش در مورد Electron و گسترش برنامه ایجاد شده در بخش های شروع سریع است. این راهنماها عبارتند از: - معماری برنامه - افزودن ویژگی ها به برنامه شما - Boilerplates و CLIs
دسته مراحل پیشرفته حاوی راهنماهای پیشرفته تری با هدف پیکربندی و تنظیم دقیق برنامه Electron شما است: - تست و اشکال زدایی - دسترسی - امنیت - به روز رسانی ها
2- کاهش تعداد صفحات مستندات. نسخه فعلی اسناد حاوی مقدار مشخصی از محتوای همپوشانی و دستورالعمل های دسته بندی نشده است. به عنوان مثال: - نصب و نصب Electron در Writing Your First App - Application Packaging and Packaging App Your App Your in a File in Application Distribution - دستورالعمل های دسته بندی نشده در دسته های In Detail و Advanced: پیشنهاد: اسناد زیر را به GitHub منتقل کنید و از آن حذف کنید. مستندات اصلی این اسناد مختص دستورالعمل‌های توسعه الکترون هستند و مخزن منبع اولین جایی است که باید به دنبال آنها بگردید: - توسعه الکترون - توسعه کروم - توسعه V8 - مشکلات در الکترون - وصله‌ها در الکترون - درخواست‌های کشش - ساختار فهرست کد منبع - تست - کدگذاری سبک
ایده اصلی کاهش، خلاص شدن از شر تعداد زیادی از راهنماهای موجود، پیوستن اطلاعات پازل پراکنده به یکدیگر و ارائه نسخه ساختار یافته تر، آسان تر و کاربرپسندتر از مستندات Electron است.
هفته های 5 تا 7
هفته پنجم به تهیه یک الگو (روشی) از نحوه ادغام الکترون-آپی-دموها در مستندات اصلی اختصاص داده خواهد شد. این الگو ممکن است به شکل زیر باشد: 1. در مستندات اصلی، در بخش «افزودن ویژگی‌ها به برنامه شما»، دسته‌هایی را ایجاد کنید که در electron-api-demos 2 نشان داده شده‌اند. با مرور هر یک از دسته‌ها، نمونه‌های نمایشی را به مستندات اصلی: - نمونه کد را می توان از کد منبع یا از توضیحات ویژگی مربوطه در برنامه برداشت - هر مثال منتقل شده باید با توضیحات مرتبط دنبال شود - هر مثال فرزند (به عنوان مثال، گفتگوی خطا در کودکی از پنجره های استفاده از سیستم) باید تحت والد آن منتقل شود
نکته 1: نمونه هایی وجود دارد که هم در electron-api-demo و هم در مستندات اصلی (به عنوان مثال، میانبرهای صفحه کلید، کشیدن و رها کردن) وجود دارد. در این مورد، مثال از electron-api-demos باید در اولویت قرار گیرد و مثال در مستندات اصلی باید نادیده گرفته شود.
توجه شماره 2: بسیاری از نمونه‌ها در برنامه electron-api-demos دارای پیش‌نمایش Live Demo از ویژگی یا عملکرد توصیف‌شده هستند. این قابلیت تا زمان ادغام Electron Fiddle در هفته‌های 9-10 نادیده گرفته می‌شود.
- با رعایت سلسله مراتب جدید نمونه ها، صفحه فهرستی از تمام ویژگی های موجود برای استفاده (که در هفته 3 ایجاد شد) را به روز کنید.
هفته 6 و 7 به انتقال نمونه های الکترون-آپی-دمو به مستندات اصلی طبق الگوی شرح داده شده در بالا اختصاص داده خواهد شد. به عنوان آخرین مرحله، مخزن electron-api-demos باید حذف یا منسوخ شود.
هفته های 8 تا 10
هفته 8 به تهیه یک الگو (روشی) از نحوه ادغام Electron Fiddle در مستندات اصلی اختصاص داده خواهد شد. این ابتکار قبلاً توسط بچه‌های Electron به همراه داوطلبان جامعه راه‌اندازی شده است (جزئیات را در شماره 20442 بررسی کنید) اما نیاز به نهایی‌سازی مناسب دارد.
برای ادامه با نمونه های Fiddle، الگوی اصلی ممکن است به صورت زیر باشد: 1. یک مثال از مستندات اصلی (به عنوان مثال، شروع سریع) انتخاب کنید. در این مرحله، مستندات باید شامل نمونه‌های الکترون-api-demos نیز باشد. 2. مثال را در Electron Fiddle دوباره ایجاد کنید (با استفاده از کد نمونه یا کد منبع به عنوان نقطه شروع). 3. Fiddle را به صورت محلی در یک پوشه ذخیره کنید. 4. مثال را به /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO] منتقل کنید. * فهرست نمونه‌های تکمیل‌شده در بخش «فهرست نسخه‌های نمایشی» شماره توضیح داده شده است. 5. دکمه "راه اندازی در کمانچه" را همانطور که در نظر اولیه در شماره 2848 توضیح داده شد اضافه کنید.
هفته‌های 9 و 10 به ادغام نمونه‌های الکترون-آپی-دمو (که قبلاً به کمانچه‌ها تبدیل شده‌اند) در مستندات اصلی طبق الگوی شرح داده شده در بالا اختصاص داده خواهد شد.
هفته 11
این هفته پس از انتقال موفقیت آمیز مخزن الکترون-آپی-دموس و نمونه های الکترون کمانچه، به طور کامل به نهایی شدن پروژه نگارش اختصاص خواهد یافت. این شامل موارد زیر است: - بررسی اینکه همه نمونه‌های کد موجود دارای دکمه «راه‌اندازی در کمانچه» هستند - بررسی اینکه همه نمونه‌های کد موجود به‌درستی به‌عنوان کمانچه کار می‌کنند - بررسی اینکه اسناد اصلی دیگر به مخزن الکترون-api-demos اشاره نمی‌کنند.
هفته 12
نهایی شدن کار انجام شده. چک های پذیرش