Bu sayfada, Google Dokümanlar Sezonu için kabul edilen bir teknik yazım projesinin ayrıntıları yer almaktadır.
Proje özeti
- Açık kaynak kuruluşu:
- Elektron
- Teknik yazar:
- Mister Gold
- Projenin adı:
- Electron Eğitim Akışı
- Proje uzunluğu:
- Standart uzunluk (3 ay)
Proje açıklaması
PROJE ÖZETİ
Electron, JavaScript, HTML ve CSS ile platformlar arası masaüstü uygulamaları oluşturmak için kullanılan en popüler araçlardan biridir. Electron'da oluşturulan uygulama koleksiyonunda yaklaşık 900 giriş bulunuyor ve bu liste sürekli olarak büyüyor. Visual Studio Code, Atom, Postman, Slack, GitKraken gibi en popüler geliştirici araçlarından bazıları Electron'da geliştirilmiştir.
Electron'un popülerliği, basit öğrenme eğrisi ve düşük giriş eşiğinden kaynaklanır. JavaScript, HTML ve CSS paketini bilen herkes kendi uygulamasını oluşturabilir. Büyük genel büyüme oranları, anlaşılması ve kullanılması kolay eğitici içerikler ve başlangıç kılavuzları hazırlamanız gerektiğini gösteriyor.
Projenin amacı, Electron çerçevesine yeni katılan uygulama geliştiricilerin güvenini kazanmak ve kendi Electron uygulamalarını sıfırdan geliştirirken tutarlı ve basit bir deneyim sunmaktır.
Proje Sorunları
Aşağıda, Electron eğitim belgeleriyle ilgili en önemli sorunların listesi yer almaktadır: 1. Uygulama geliştirme adımları hakkında net olmayan bir başlangıç noktası ve sezgisel olmayan giriş bilgileri 2. Uygulama geliştirme süreciyle ilgili dağınık ve gereksiz bilgiler 3. Tek bir doğru kaynaktan yararlanmayan, "başlarken" kılavuz talimatlarının dağınık parçaları
PROJE TEKLİFİ
Projenin hedefine ve yukarıda ana hatlarıyla açıklanan sorunlara göre önerilen geliştirmeler aşağıda listelenmiştir: 1. Mevcut kılavuzları güncelleyin. İlk adımların sorunsuz ve tutarlı olmasını sağlamak için aşağıdaki dokümanlar, basitten daha karmaşıka kademeli bir geçişle güncellenmelidir: - Geliştirici Ortamı - İlk Electron Uygulamanızı Yazma - Uygulamanıza Özellik Ekleme (özet sayfası oluşturun) - Uygulama Paketleme ve Dağıtım 2. Doküman dizini yeniden yapılandırılmalıdır. Yeni geliştiricilere başlangıç için nelerin gerekli olduğunu ve sonraki adımlar olarak nelerin değerlendirilebileceğini göstermek amacıyla, dokümanlar sayfasında ilk uygulamayı olabildiğince hızlı bir şekilde yayınlamak için adımların hem görsel hem de bağlamsal olarak ayrılması gerekir. Yeniden yapılanma, olası sonraki adımlarla ilgili rehberlik de içerir. 3. Uygulama geliştirme belgelerini düzenleyin ve birleştirin. Tüm özellikler için nasıl yükleneceği/etkinleştirileceği, hızlıca nasıl başlatılacağı, ilk lansmandan sonra uygulamayla nasıl çalışılacağı ve nasıl dağıtılacağıyla ilgili birleşik bir talimat grubu olmalıdır. 4. electron-api-demos deposunu dokümanlara ekleyin. electron-api-demos deposu, Electron uygulamanıza nasıl özellik ekleneceğini gösteren bir dizi örnek içerir. Bu bilgilerin, tek ve doğru bir içerik kaynağı stratejisiyle tutarlı olması için Uygulamanıza Özellik Ekleme kılavuzuna eklenmesi gerekir. 5. Electron Fiddle örneklerini dokümanlara entegre edin. Bu adım, yeni geliştiricilerin adımları manuel olarak tekrarlamak zorunda kalmadan belirli bir kod parçasının nasıl çalıştığını görmesini kolaylaştırır. Entegrasyon, güncellenen eğitimler için kod örnekleri yazma ve kod bloklarına "Fiddle'de başlat" düğmesi eklemeyi içerir.
Önemli Dakikalar
Başvuru İnceleme Dönemi - Birlikte çalışacağınız topluluk ve kişilerle tanışın. Topluluk katkısı kılavuzları ve en iyi uygulamaları öğrenin. İlk katkıları yapın. Topluluk Bağışı - Topluluğu keşfedin. Electron dokümanlarının mevcut durumunu inceleyin. Zayıf noktaları belirlemek. 1. Hafta: Proje aşamaları ve teslim edilecekler konusunda mentorlarla uyumlu olun 2. Hafta: Geliştirici Ortamı ve İlk Electron Uygulamanızı Yazma sayfalarını gözden geçirin 3. Hafta: Uygulama Mimarisi, Uygulamanıza Özellik Ekleme, Uygulama Paketleme ve Dağıtım sayfalarını gözden geçirin. Uygulamaya eklenebilecek özelliklerin listesini içeren bir özet sayfası oluşturun 4. Hafta - Doküman dizini yeniden yapılandırın 5. Hafta - electron-api-demos'un ana dokümana nasıl entegre edileceğine dair bir şablon hazırlayın 6. ve 7. Haftalar - electron-api-demos deposunu taşıyın 8. Hafta - Electron Fiddle'in ana dokümana nasıl entegre edileceğine dair bir şablon hazırlayın. İlk örneği yazın. 9. ve 10. haftalar: Electron Fiddle'i ana dokümana entegre edin 11. hafta: electron-api-demos deposunu ve Electron Fiddle örneklerini taşıdıktan sonra ana doküman yapısının ve sayfalarının tamamlanması 12. hafta: Sonuçları değerlendirme
AYRINTILI ARA HEDEF DÖKÜMÜ
BAŞVURU İNCELEME DÖNEMİ Bu dönemin ilk kısmı, topluluk kanallarını ve kaynak kodunu kontrol etmeye ve projeye adanmış kişilerle iletişime geçmeye ayrılır.
Dönemin ikinci bölümünde ise genel olarak katkı kültürünü kontrol etmek, katkı kılavuzlarını ve en iyi uygulamaları incelemek için çalışacağız. Bu, akışın işleyiş şeklini göstermek için ilk katkılarınızın zamanıdır.
TOPLULUK BAĞI
Bu süre, doküman klasörünün ve yol haritasının daha ayrıntılı bir şekilde incelenmesine ayrılacak. Bu bilgilere dayanarak, geliştirilebilecek zayıf noktalar (ör. eksik veya eksik parçalar) belirlenebilir. Boşlukları doldurmak için (mümkünse) çekme istekleri oluşturun.
1. HAFTA - 2. HAFTA
İlk hafta beklenen ara hedefler ve bunların zamanında teslim edilmesi için mentorlarla iletişim kurmaya ayrılacaktır.
İkinci hafta, Geliştirici Ortamı ve İlk Electron Uygulamanızı Yazma sayfalarının gözden geçirilmesiyle ilgili olacak. Geliştirici Ortamı sayfasında genel bakışı yeniden yazma ve gözden geçirme işlemleri yapılır. İlk Electron Uygulamanızı Yazma sayfasında, sayfayı net bir başlangıç ve bitiş noktası olan tutarlı bir adım adım kılavuz haline getirmek, gereksiz bilgileri (ör. Electron Geliştirme Özet ve Bu örneği dene bölümü altındaki iki benzer kod bloğu) kaldırmak yer alacak.
Teslimatlar: Electron uygulamalarını nasıl hızlı başlangıç yapacağınıza ilişkin, gözden geçirilmiş ve uygulaması kolay giriş kılavuzları.
3. HAFTA
Bu hafta: 1. Uygulama mimarisi sayfasında yapılacak iyileştirmelere odaklanacağız. Bu kapsamda: - Ana ve Oluşturucu İşlemleri bölümündeki mevcut bilgilerin, ilk kez okuyan kullanıcılar için basit ve daha sezgisel hale getirecek şekilde yeniden yazılması - Mimarinin, süreçlerin nasıl bağlandığı, nasıl iletişim kurduğu ve temel farklılıklarının görsel temsilinin eklenmesi Görsel örnekleri: Bir, İki, Üç (düşük kaliteli). 2. Electron uygulamanıza ekleyebileceğiniz tüm özelliklerle ilgili bilgilerin birleştirilmesi. Kılavuzların yeniden yazılması da buna dahildir. Böylece, bir özelliği yükleme/etkinleştirme ile ilgili birleştirilmiş bir dizi talimat ve özelliğin nasıl çalıştığına dair bir örnek yer alacaktır. Ayrıca, kullanılabilir tüm özelliklerin listelendiği yeni bir sayfa (özet) oluşturulacaktır. Birleştirilmiş talimatlar şu şekilde görünebilir: - Genel bakış - Örnek: - Kod örneği - Görsel örnek (mümkün olduğunda)
- Uygulama Dağıtımı sayfasının basitleştirilmesi. Bu adımlar arasında: a. Uygulama Dağıtımı kılavuzunda uygulama paketi birleştirme b. dağıtım yöntemlerini otomatik ve manuel olarak ayırma c. otomatik dağıtıma örnek olarak elektron dövmesini ele alma d. Uygulama Paketleme sayfasından asar hakkındaki bilgileri alma ve kaynak dosyalarının kopyalanmasını ve asar arşivini manuel dağıtım örnekleri olarak açıklama. #### 4. HAFTA Bu hafta belge dizinini yeniden yapılandırmaya odaklanacağız. Şunları içermektedir:
1 - Mevcut kılavuzları en az üç kategoriye ayırın: a. Hızlı Başlangıç Kılavuzu b. Temel bilgileri öğrenme c. İleri düzey adımlar
Hızlı Başlangıç kategorisinde, yeni kullanıcıların sıfırdan hızlı başlangıç yapmasına olanak tanıyacak tutarlı bir rehber dizisi oluşturmak için temel eğitimler (yükleme, yapılandırma, dağıtım) yer alır. Her kılavuz, serideki önceki/sonraki kılavuzların bağlantılarını içermelidir.
Yapı şu şekilde görünebilir: 1. Ön koşullar 2. Electron'u yükleyin 3. Temel bir uygulama oluşturun 4. Uygulamayı paketleme/dağıtma
Hızlı Başlangıç bölümünü tamamlayan kullanıcı, Electron uygulamalarının işleyişine dair temel bilgileri öğrenecek ve tamamen çalışan, dağıtılabilir bir Electron uygulamasına sahip olacaktır.
Temel bilgileri öğrenme kategorisinde, Electron hakkındaki bilginizi güçlendirmeyi ve Hızlı Başlangıç bölümlerinde oluşturulan uygulamayı genişletmeyi amaçlayan rehberler yer alır. Bu rehberler şunları içerir: - Uygulama Mimarisi - Uygulamanıza Özellik Ekleme - Şablonlar ve CLI'ler
Gelişmiş adımlar kategorisinde, Electron uygulamanızı yapılandırmayı ve ince ayarlarını yapmayı amaçlayan daha gelişmiş kılavuzlar yer alır: - Test ve Hata Ayıklama - Erişilebilirlik - Güvenlik - Güncellemeler
2 - Belge sayfalarının sayısını azaltma. Belgelerin mevcut sürümünde, belirli ölçüde örtüşen içerikler ve sınıflandırılmamış talimatlar yer alıyor. Örneğin: - İlk Uygulamanızı Yazmada Electron'u Yükleme ve Yükleme - Uygulama Paketleme ve Uygulamanızı Uygulama Dağıtımı içinde bir Dosyaya Paketleme - Ayrıntılı ve Gelişmiş kategorilerinde kategorize edilmemiş talimatlar: Öneri: Aşağıdaki dokümanları GitHub'a taşıyın ve ana dokümanlardan hariç tutun. Bu belgeler, Electron geliştirme yönergelerine özeldir ve araştırılması gereken ilk yer kaynak deposudur: - Elektron Geliştirme - Krom Geliştirme - V8 Geliştirme - Elektron Sorunları - Elektron Yamaları - Çekme İstekleri - Kaynak Kod Dizin Yapısı - Test - Kodlama Stili
Azaltmanın temel fikri, mevcut çok sayıda kılavuzdan kurtulmak, dağınık bilgi parçalarını bir araya getirmek ve yeni gelenlere Electron dokümantasyonunun daha yapılandırılmış, kolay gezinilebilir ve kullanıcı dostu bir sürümünü sunmaktır.
5-7. HAFTA
5. hafta, electron-api-demos'un ana dokümanlara nasıl entegre edileceğine dair bir şablon (bir yöntem) hazırlamaya ayrılacak. Bu şablon aşağıdaki gibi görünebilir: 1. Ana dokümanda, "Uygulamanıza Özellik Ekleme" bölümünde, electron-api-demos2'de temsil edilen kategorileri oluşturun. Kategorilerin her birini gözden geçirerek demo örneklerini ana belgelere aktarın: - Kod örnekleri, kaynak koddan veya uygulamadaki ilgili özelliğin açıklamasından alınabilir. - Aktarılan her örnek, ilgili açıklamadan sonra gelmelidir. - Her alt örnek (örneğin, "Sistemi kullan" iletişim kutularının alt öğesi olarak Hata iletişim kutusu), kendi üst öğesinin altına aktarılmalıdır
1. NOT: Hem electron-api-demos'da hem de ana dokümanda (ör. klavye kısayolları, sürükle ve bırak) örnekler vardır. Bu durumda, electron-api-demos'daki örnek öncelikli olur ve ana dokümanlar bölümündeki örnek yoksayılır.
2. NOT: electron-api-demos uygulamasındaki birçok örnekte, açıklanan özelliğin veya işlevin canlı önizlemesi bulunur. Bu işlev, 9. ve 10. haftalarda Electron Fiddle entegrasyonu yapılana kadar yoksayılacak.
- Kullanıma sunulan tüm özellikleri listeleyen sayfayı (3. haftada oluşturulan), yeni örnek hiyerarşisine uygun şekilde güncelleyin.
6. ve 7. haftalar, yukarıda açıklanan şablona göre electron-api-demos örneklerini ana dokümanlara aktarmaya ayrılacak. Son adım olarak electron-api-demos deposu silinmeli veya desteği sonlandırılmalıdır.
8. - 10. HAFTALAR
8. hafta, Electron Fiddle'in ana dokümanlara nasıl entegre edileceğine dair bir şablon (bir yöntem) hazırlamaya ayrılacak. Bu girişim, Electron ekibi ve topluluk gönüllüleri tarafından başlatılmış olsa da (20442 numaralı sorundaki ayrıntıları inceleyin) uygun şekilde tamamlanması gerekiyor.
Fiddle örneklerine devam etmek için temel şablon aşağıdaki gibi görünebilir: 1. Ana belgelerden bir örnek seçin (ör. hızlı başlangıç). Bu noktada, belgeler elektron-api-demos örnekleri de içermelidir; 2. Örneği Electron Fiddle'de yeniden oluşturun (başlangıç noktası olarak örnek kodu veya kaynak kodu kullanın); 3. Fiddle'ı yerel olarak bir klasöre kaydedin; 4. Örneği /docs/fiddles/[CATEGORY]/[SECTION]/[DEMO] konumuna taşıyın. * Tamamlanan örneklerin listesi, sorunun "Demo Listesi" bölümünde açıklanmaktadır. 5. 2848 numaralı sorundaki ilk yorumda açıklandığı gibi "Fiddle'da başlat" düğmesini ekleyin.
9. ve 10. haftalar, electron-api-demos örneklerini (Fiddle'lere dönüştürülmüş olan) yukarıda açıklanan şablona göre ana dokümana entegre etmeye ayrılacaktır.
11. HAFTA
Bu hafta, electron-api-demos deposu ve Electron Fiddle örnekleri başarıyla taşındıktan sonra yazma projesinin tamamlanmasına tamamen odaklanacağız. Bu işlemler arasında şunlar yer alır: - Mevcut tüm kod örneklerinde "Fiddle'de başlat" düğmesinin bulunduğundan emin olun. - Mevcut tüm kod örneklerinin Fiddle'de düzgün çalıştığından emin olun. - Ana dokümantasyonun artık electron-api-demos deposuna atıfta bulunmadığından emin olun.
12. HAFTA
Tamamlanan çalışmanın tamamlanması. Kabul kontrolleri.