Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan project
- Organisasi open source:
- Electron
- Penulis teknis:
- Mister Gold
- Nama proyek:
- Alur Tutorial Electron
- Durasi project:
- Durasi standar (3 bulan)
Project description
RINGKASAN PROJECT
Electron adalah salah satu alat paling populer untuk mem-build aplikasi desktop lintas platform dengan JavaScript, HTML, dan CSS. Kumpulan aplikasi yang dibuat di Electron memiliki hampir 900 entri dan daftar ini terus bertambah. Beberapa alat developer yang paling populer seperti Visual Studio Code, Atom, Postman, Slack, GitKraken dibuat di Electron.
Popularitas Electron terletak pada kurva pembelajarannya yang sederhana dan nilai minimum masuk yang rendah - siapa saja yang memahami JavaScript, HTML, CSS stack dapat membuat aplikasi mereka sendiri. Rasio pertumbuhan keseluruhan yang sangat besar menentukan perlunya membuat tutorial dan panduan memulai yang mudah dipahami dan digunakan.
Tujuan project ini adalah untuk memberikan kepercayaan kepada builder aplikasi yang baru menggunakan framework Electron dan memberi mereka pengalaman yang konsisten dan sederhana dalam mengembangkan aplikasi Electron mereka sendiri dari awal.
Masalah Project
Berikut adalah daftar masalah paling penting yang terkait dengan dokumentasi tutorial Electron: 1. Titik awal yang tidak jelas dan informasi pengantar yang tidak intuitif tentang langkah-langkah pengembangan aplikasi 2. Informasi yang tersebar dan redundan terkait proses pengembangan aplikasi 3. Bagian-bagian petunjuk panduan "memulai" yang tidak teratur tanpa satu sumber tepercaya
PROPOSAL PROYEK
Sesuai dengan tujuan project, dan masalah yang diuraikan di atas, berikut ini adalah daftar peningkatan yang diusulkan: 1. Perbarui panduan yang ada. Agar langkah pertama berjalan lancar dan konsisten, dokumen berikut harus diperbarui dengan peralihan bertahap dari yang sederhana ke yang lebih kompleks: - Lingkungan Developer - Menulis Aplikasi Electron Pertama Anda - Menambahkan Fitur ke Aplikasi Anda (buat halaman ringkasan) - Pengemasan dan Distribusi Aplikasi 2. Menyusun ulang direktori dokumentasi. Untuk menunjukkan kepada developer baru hal-hal yang penting untuk memulai dan hal-hal yang dapat dipertimbangkan sebagai langkah lebih lanjut, halaman dokumen harus memiliki pembagian langkah-langkah secara visual dan kontekstual untuk membuat aplikasi pertama aktif secepat mungkin. Penyusunan ulang juga mencakup panduan tentang kemungkinan langkah berikutnya. 3. Mengatur dan menyatukan dokumentasi pengembangan aplikasi. Semua fitur harus memiliki serangkaian petunjuk terpadu tentang cara menginstal/mengaktifkannya, cara memulai dengan cepat, cara menggunakan aplikasi setelah peluncuran pertama, dan cara mendistribusikannya. 4. Menyertakan repositori electron-api-demos dalam dokumentasi. Repositori electron-api-demos berisi serangkaian contoh yang menunjukkan cara menambahkan fitur ke aplikasi Electron Anda. Informasi ini harus disertakan dalam panduan Menambahkan Fitur ke Aplikasi Anda agar konsisten dengan strategi konten single source of truth. 5. Mengintegrasikan contoh Electron Fiddle ke dalam dokumentasi. Langkah ini akan memudahkan developer baru untuk melihat cara kerja bagian kode tertentu tanpa harus mengulangi langkah-langkahnya secara manual. Integrasi ini mencakup penulisan contoh kode untuk tutorial yang diperbarui dan menambahkan tombol “Launch in Fiddle” ke blok kode.
Linimasa
Periode Peninjauan Permohonan - Memahami komunitas dan orang-orang yang akan bekerja sama. Pelajari panduan kontribusi komunitas dan praktik terbaik. Buat kontribusi pertama. Community Bonding - Jelajahi komunitas. Periksa status dokumentasi Electron saat ini. Identifikasi titik lemah. Minggu 1 - Menyelaraskan dengan mentor tentang pencapaian dan hasil project Minggu 2 - Merevisi halaman Lingkungan Developer dan Menulis Aplikasi Electron Pertama Anda Minggu 3 - Merevisi halaman Arsitektur Aplikasi, Menambahkan Fitur ke Aplikasi Anda, dan mendistribusikan Aplikasi. Membuat halaman ringkasan dengan daftar fitur yang dapat ditambahkan ke aplikasi Minggu ke-4 - Melakukan restrukturisasi direktori dokumentasi Minggu ke-5 - Menyiapkan template tentang cara electron-api-demos akan diintegrasikan ke dalam dokumentasi utama Minggu ke-6 - 7 - Memigrasikan repositori electron-api-demos Minggu ke-8 - Menyiapkan template tentang cara Electron Fiddle akan diintegrasikan ke dalam dokumentasi utama. Tulis contoh pertama. Minggu ke-9 - 10 - Mengintegrasikan Elektron Fiddle ke dalam dokumentasi utama Minggu 11 - Finalisasi struktur dan halaman dokumentasi utama setelah memigrasikan repositori elektron-api-demos dan contoh Electron Fiddle Minggu 12 - Mengevaluasi hasil
PERINCIAN PENCAPAIAN MENDETAIL
PERIODE PENINJAUAN APLIKASI Bagian pertama periode ini akan difokuskan untuk memeriksa channel komunitas dan kode sumber, serta menghubungi orang-orang yang berdedikasi untuk project tersebut.
Bagian kedua dari periode ini akan dikhususkan untuk memeriksa budaya kontribusi secara umum, memeriksa panduan kontribusi, dan praktik terbaik. Ini akan menjadi waktu untuk kontribusi pertama untuk melihat cara kerja alur.
PENGHUBUNGAN KOMUNITAS
Kali ini akan dikhususkan untuk pemeriksaan yang lebih mendalam tentang folder dokumentasi beserta roadmap-nya. Berdasarkan informasi tersebut, Anda dapat mengidentifikasi titik lemah (misalnya, bagian yang tidak lengkap atau tidak ada) yang dapat ditingkatkan. Buat permintaan pull (jika memungkinkan) untuk mengisi kesenjangan.
MINGGU 1 - MINGGU 2
Minggu pertama akan dikhususkan untuk komunikasi dengan mentor guna menyelaraskan pencapaian yang diharapkan dan penyampaiannya yang tepat waktu.
Minggu kedua Anda akan merevisi Lingkungan Pengembang dan Menulis halaman Aplikasi Elektron Pertama Anda. Untuk halaman Lingkungan Developer, halaman ini akan mencakup penulisan ulang ringkasan umum dan pemeriksaan tata bahasa. Untuk halaman Menulis Aplikasi Electron Pertama Anda, halaman ini akan menyertakan panduan langkah demi langkah yang konsisten dengan titik awal dan akhir yang jelas, serta menghapus informasi yang berlebihan (seperti dua blok kode yang serupa di bagian Electron Development in a Nutshell dan Trying this example).
Hasil: Panduan pengantar yang direvisi dan mudah diikuti tentang cara memulai cepat dengan aplikasi Electron.
MINGGU KE-3
Minggu ini akan dikhususkan untuk: 1. peningkatan halaman Arsitektur Aplikasi. Hal ini mencakup: - penulisan ulang informasi yang ada di bagian Proses Utama dan Perender untuk membuatnya sederhana dan lebih intuitif bagi pembaca pertama kali - menambahkan representasi visual arsitektur, cara proses terhubung, cara proses berkomunikasi, dan perbedaan intinya. Contoh visual: Satu, Dua, Tiga (kualitas rendah). 2. penyatuan informasi tentang semua fitur yang dapat Anda tambahkan ke aplikasi Electron. Hal ini termasuk menulis ulang panduan sehingga panduan tersebut akan memiliki kumpulan petunjuk terpadu tentang cara menginstal/mengaktifkan fitur beserta contoh cara kerja fitur tersebut. Selain itu, halaman baru (ringkasan) yang mencantumkan semua fitur yang tersedia untuk digunakan akan dibuat. Petunjuk terpadu mungkin terlihat seperti berikut: - Ringkasan - Contoh: - Contoh kode - Contoh visual (jika memungkinkan)
- penyederhanaan halaman Distribusi Aplikasi. Hal ini mencakup: a. menggabungkan Pengemasan Aplikasi ke dalam panduan Distribusi Aplikasi b. membagi metode distribusi menjadi otomatis dan manual c. mengambil electron-forge sebagai contoh distribusi otomatis d. mengambil informasi tentang asar dari halaman Pengemasan Aplikasi dan menjelaskan cara menyalin file sumber dan membuat arsip asar sebagai contoh distribusi manual. #### MINGGU KE-4 Minggu ini akan dikhususkan untuk menyusun ulang direktori dokumentasi. Ini mencakup:
1 - membagi panduan yang ada menjadi setidaknya tiga kategori: a. Panduan memulai b. Mempelajari dasar-dasarnya c. Langkah lanjutan
Kategori Memulai Cepat akan berisi tutorial dasar (penginstalan, konfigurasi, distribusi) untuk membuat serangkaian panduan yang konsisten yang akan memungkinkan pendatang baru memulai cepat dari awal. Setiap panduan harus berisi link ke panduan sebelumnya/berikutnya dalam seri.
Strukturnya mungkin terlihat seperti berikut: 1. Prasyarat 2. Instal Electron 3. Buat aplikasi dasar 4. Memaketkan/Mendistribusikan aplikasi
Setelah menyelesaikan bagian Mulai Cepat, pengguna akan mengetahui dasar-dasar cara kerja aplikasi Electron dan akan memiliki aplikasi Electron yang dapat didistribusikan dan berfungsi sepenuhnya.
Kategori Mempelajari dasar-dasar akan berisi panduan yang bertujuan untuk memperkuat pengetahuan tentang Electron dan memperluas aplikasi yang dibuat di bagian Mulai Cepat. Panduan ini mencakup: - Arsitektur Aplikasi - Menambahkan Fitur ke Aplikasi Anda - Boilerplate dan CLI
Kategori Langkah lanjutan akan berisi panduan lanjutan lainnya yang ditujukan untuk mengonfigurasi dan menyesuaikan aplikasi Electron Anda: - Pengujian dan Proses Debug - Aksesibilitas - Keamanan - Update
2 - mengurangi jumlah halaman dokumentasi. Versi dokumentasi saat ini berisi konten yang tumpang tindih dalam tingkatan tertentu dan instruksi yang tidak dikategorikan. Misalnya: - Menginstal dan Menginstal Elektron dalam Menulis Aplikasi Pertama Anda - Pengemasan dan Pengemasan Aplikasi ke File dalam Distribusi Aplikasi - Petunjuk yang Tidak Dikategorikan dalam kategori Detail dan Lanjutan: Saran: pindahkan dokumen berikut ke GitHub dan kecualikan dari dokumentasi utama. Dokumen ini khusus untuk panduan pengembangan Electron dan repositori sumber adalah tempat pertama untuk mencarinya: - Mengembangkan Electron - Pengembangan Chromium - Pengembangan V8 - Masalah di Electron - Patch di Electron - Permintaan Pull - Struktur Direktori Kode Sumber - Pengujian - Gaya Coding
Ide utama pengurangan ini adalah untuk menghilangkan jumlah panduan yang berlebihan, menggabungkan potongan-potongan informasi teka-teki yang tersebar, dan memberi pendatang baru versi dokumentasi Electron yang lebih terstruktur, mudah dijelajahi, dan mudah digunakan.
MINGGU 5 - 7
Minggu ke-5 akan dikhususkan untuk menyiapkan template (cara) bagaimana electron-api-demos akan diintegrasikan ke dalam dokumentasi utama. Template ini mungkin terlihat seperti berikut: 1. Dalam dokumentasi utama, di bagian “Menambahkan Fitur ke Aplikasi Anda”, buat kategori yang diwakili dalam electron-api-demos 2. Dengan melihat setiap kategori, transfer contoh demo ke dokumentasi utama: - Contoh kode dapat diambil dari kode sumber atau dari deskripsi fitur yang sesuai dalam aplikasi - Setiap contoh yang ditransfer harus diikuti dengan deskripsi terkait - Setiap contoh turunan (misalnya, Dialog error sebagai turunan dari Gunakan dialog sistem) harus ditransfer di bawah induknya
CATATAN #1: ada contoh yang ada baik dalam {i>elektron-api-demos<i} dan dalam dokumentasi utama (misalnya, pintasan keyboard, {i>drag and drop<i}). Dalam hal ini, contoh dari elektronik-api-demo harus diprioritaskan dan contoh dalam dokumentasi utama harus diabaikan.
CATATAN #2: Banyak contoh dalam aplikasi elektronik-api-demos memiliki pratinjau Demo Live fitur atau fungsi yang dijelaskan. Fungsi ini akan diabaikan hingga integrasi Electron Fiddle pada Minggu 9-10.
- Perbarui halaman yang mencantumkan semua fitur yang tersedia untuk digunakan (yang dibuat selama Minggu 3) dengan mengikuti hierarki contoh baru.
Minggu ke-6 dan ke-7 akan dikhususkan untuk mentransfer contoh elektron-api-demos ke dokumentasi utama sesuai dengan {i>template<i} yang dijelaskan di atas. Sebagai langkah terakhir, repositori elektronik-api-demos harus dihapus atau tidak digunakan lagi.
MINGGU 8 - 10
Minggu ke-8 akan didedikasikan untuk menyiapkan {i>template<i} (sebuah cara) tentang bagaimana Electron Fiddle akan diintegrasikan ke dalam dokumentasi utama. Inisiatif ini telah diluncurkan (lihat detail dalam masalah #20442) oleh tim Electron bersama dengan sukarelawan komunitas, tetapi memerlukan finalisasi yang tepat.
Untuk melanjutkan dengan contoh Fiddle, template dasarnya mungkin terlihat seperti berikut: 1. Pilih contoh dari dokumentasi utama (misalnya, panduan memulai). Pada tahap ini, dokumentasi juga harus berisi contoh electron-api-demos; 2. Membuat ulang contoh di Electron Fiddle (menggunakan kode contoh atau kode sumber sebagai titik awal); 3. Simpan Fiddle secara lokal ke folder; 4. Pindahkan contoh ke /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO]. * Daftar contoh yang telah selesai dijelaskan di bagian “Daftar Demo” dalam masalah ini. 5. Tambahkan tombol “Launch in Fiddle” seperti yang dijelaskan dalam komentar awal pada masalah #2848.
Minggu ke-9 dan ke-10 akan dikhususkan untuk mengintegrasikan contoh electron-api-demos (yang telah dikonversi menjadi Fiddle) ke dokumentasi utama sesuai dengan template yang dijelaskan di atas.
MINGGU KE-11
Minggu ini akan sepenuhnya difokuskan untuk finalisasi proyek penulisan setelah keberhasilan migrasi repositori Electron-api-demos dan sampel Electron Fiddle. Ini termasuk: - memeriksa apakah semua contoh kode yang ada memiliki tombol "Launch in Fiddle" - memeriksa apakah semua contoh kode yang ada berfungsi dengan baik sebagai Fiddles - memeriksa apakah dokumentasi utama tidak lagi merujuk ke repositori elektronik api-demos
MINGGU KE-12
Penyelesaian pekerjaan yang telah selesai. Cek penerimaan.