Bu sayfa, Google Dokümanlar Sezonu için kabul edilen bir teknik yazı projesinin ayrıntılarını içerir.
Proje özeti
- Açık kaynak kuruluşu:
- Elektron
- Teknik yazar:
- Kısmetli Altın
- Projenin adı:
- Elektron Öğretici Akışı
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
PROJE ÖZETİ
Electron; JavaScript, HTML ve CSS ile platformlar arası masaüstü uygulamaları oluşturmak için en popüler araçlardan biridir. Electron'da oluşturulan bir uygulama koleksiyonunda yaklaşık 900 giriş vardır ve bu liste sürekli olarak büyümektedir. Visual Studio Code, Atom, Postman, Slack ve 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ğrisinde ve düşük giriş eşiğinde yatar. JavaScript, HTML, CSS yığınını bilen herkes kendi uygulamalarını oluşturabilir. Yüksek genel büyüme oranları, anlaşılması ve kullanılması kolay eğiticiler ve başlangıç kılavuzları oluşturma ihtiyacını ortaya koyuyor.
Projenin hedefi, Electron çerçevesiyle çalışmaya yeni başlayan uygulama geliştiricilerin güvenini kazanmak ve kendi Electron uygulamalarını sıfırdan geliştirirken tutarlı ve modern bir deneyim sunmaktır.
Proje Sorunları
Electron eğiticileri belgeleriyle ilgili en önemli sorunların listesi aşağıda verilmiştir: 1. Başlangıç noktası anlaşılır değil ve uygulama geliştirme adımlarına ilişkin pratik olmayan bilgiler 2. Uygulama geliştirme süreciyle ilgili dağınık ve gereksiz bilgiler 3. "Başlangıç" bölümündeki dağınık haldeki kılavuz talimatları, tek ve doğru bir kaynak değildir
PROJE TEKLİFİ
Projenin hedefine ve yukarıda özetlenen sorunlara göre, önerilen geliştirmelerin listesi şu şekildedir: 1. Mevcut kılavuzları güncelleyin. İlk adımların sorunsuz ve tutarlı olması için aşağıdaki belgelerin basitten daha karmaşıka doğru kademeli geçişle güncellenmesi gerekir: - Geliştirici Ortamı - İlk Electron Uygulamanızı Yazma - Uygulamanıza Özellik Ekleme (özet sayfası oluşturma) - Uygulama Paketleme ve Dağıtım 2. Belge dizinini yeniden yapılandırın. Yeni geliştiricilere, işe başlarken gerekli olan ve sonraki adımlar olarak nelerin kabul edilebileceği hakkında fikir vermek amacıyla, ilk uygulamanın mümkün olduğunca hızlı bir şekilde hayata geçirilmesi için adımlar hem görsel hem de bağlamsal olarak bölümlere ayrılmalıdır. Yeniden yapılandırma, atılması gereken adımlar konusunda yol gösterici bilgiler de içerir. 3. Uygulama geliştirme belgelerini düzenleyin ve birleştirin. Tüm özelliklerde, uygulamanın nasıl yükleneceği/etkinleştirileceği, nasıl hızlı bir şekilde başlanacağı, bir uygulamayı ilk lansmandan sonra nasıl kullanacağınız ve nasıl dağıtılacağı ile ilgili birleşik talimatlar bulunmalıdır. 4. Belgelere elekron-api-demos deposunu ekleyin. Electron-api-demos deposu, Electron uygulamanıza nasıl özellik ekleyeceğinizi gösteren bir dizi örnek içerir. Bu bilgiler, tek ve doğru bir içerik stratejisi ile tutarlı olması için Uygulamanıza Özellik Ekleme kılavuzuna eklenmelidir. 5. Electron Fiddle örneklerini belgelere entegre etme. Bu adım, yeni geliştiricilerin belirli bir kod parçasının nasıl çalıştığını adımları manuel olarak tekrarlamalarına gerek kalmadan görmelerini kolaylaştıracaktır. Entegrasyon, güncellenen eğiticiler için kod örnekleri yazmayı ve kod bloklarına "Fiddle'da başlat" düğmesini eklemeyi içerir.
Önemli Dakikalar
Başvuru İnceleme Dönemi - Topluluğu ve birlikte çalışacağınız insanları tanıyın. Topluluk katkısı kılavuzlarını ve en iyi uygulamaları öğrenin. İlk katkıları yapın. Topluluk Takibi: Topluluğu keşfedin. Electron belgelerinin mevcut durumunu inceleyin. Zayıf noktaları belirleyin. 1. Hafta - Mentorlarla projenin ara hedefleri ve teslimatları konusunda uzlaşın 2. Hafta - Geliştirici Ortamını Gözden Geçirme ve İlk Electron Uygulama Sayfalarınızı Yazma 3. Hafta - Uygulama Mimarisini Gözden Geçirme, Uygulamanıza Özellik Ekleme, Uygulama Paketleme ve dağıtım sayfaları. Uygulamaya eklenebilecek özelliklerin listesini içeren bir özet sayfası oluşturun 4. Hafta - Doküman dizinini yeniden yapılandırın 5. Hafta - Elekron-api-demos'un ana dokümanlara nasıl entegre edileceğiyle ilgili bir şablon hazırlayın 6. - 7. Hafta - Elektron-api-demos deposunu taşıyın 8. Hafta - Ana belgelerin nasıl entegre edileceğiyle ilgili bir şablon hazırlayın. İlk örneği yazın. 9 - 10. Hafta - Elektron Kemeri'ni ana belgelere entegre etme 11. Hafta - Elektron-api-demos deposu ve Electron Fiddle numunelerini taşıdıktan sonra ana belge yapısının ve sayfaların kesinleşmesi 12. Hafta - Sonuçların değerlendirilmesi
ARA HEDEFLERİN AYRINTILI DÖKÜMÜ
BAŞVURU İNCELEME DÖNEMİ Dönemin ilk bölümünde topluluk kanalları ile kaynak kodu kontrol edilecek ve projeye bağlı kişilerle iletişime geçilecektir.
Dönemin ikinci bölümünde ise katkı kılavuzları ve en iyi uygulamalar incelenecek ve genel olarak katkı kültürünü incelemeye ayrılacağız. Bu, akışın nasıl çalıştığını görmek için ilk kez katkıda bulunma zamanıdır.
TOPLULUK BAĞLAMASI
Bu süre, belge klasörünün yol haritasıyla birlikte daha ayrıntılı bir şekilde incelenmesine ayrılacaktır. Bu bilgiler ışığında, iyileştirilebilecek zayıf noktaları (ör. eksik veya eksik parçalar) belirlemek mümkün olabilir. Boşlukları doldurmak için çekme istekleri (mümkünse) 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ılacak.
İkinci hafta, Geliştirici Ortamını Gözden Geçirme ve İlk Electron Uygulaması sayfalarınızı yazma hakkında olacaktır. Geliştirici Ortamı sayfası için genel bakış ve gözden geçirme işlemlerinin yeniden yazılmasını içerir. "İlk Elektron Uygulamanızı Yazma" sayfası için, sayfanın net başlangıç ve bitiş noktalarına sahip tutarlı bir adım adım kılavuza sahip olması, gereksiz bilgilerin kaldırılması (ör. Electron Development in a Nutshell altında iki benzer kod bloğu ve Bu örnek bölümünü deneme) içerir.
Teslimatlar: Electron uygulamalarına nasıl hızlı başlangıç yapılacağıyla ilgili, gözden geçirilmiş ve uygulaması kolay tanıtım kılavuzları.
3. HAFTA
Bu hafta aşağıdaki konular ele alınacaktır: 1. Uygulama Mimarisi sayfasındaki iyileştirmeler. Bu kapsamda: - Ana ve Oluşturucu İşlemleri bölümündeki mevcut bilgilerin, ilk kez okuyanlar için daha basit ve sezgisel olması amacıyla yeniden yazılması - mimarinin görsel temsilinin, süreçlerin nasıl bağlandığı, nasıl iletişim kurduklarının ve aralarındaki temel farkın görsel temsilinin eklenmesi. Görsel örnekleri: Bir, İki, Üç (düşük kalite). 2. Electron uygulamanıza ekleyebileceğiniz tüm özelliklerle ilgili bilgilerin birleştirilmesi. Bu bağlamda, bir özelliğin nasıl yükleneceği/etkinleştirileceğine ilişkin bir dizi talimat ve özelliğin nasıl çalıştığına dair bir örnek olacak şekilde kılavuzların yeniden yazılması da gerekir. Ayrıca, kullanılabilir tüm özelliklerin listelendiği yeni bir sayfa (özet) oluşturulur. Birleştirilmiş talimatlar aşağıdaki gibi görünebilir: - Genel Bakış - Örnek: - Kod örneği - Görsel örnek (mümkünse)
- basitleştirdik. Bu çalışma şunları kapsar: a. Uygulama Paketinin Uygulama Dağıtımı kılavuzunda birleştirilmesi b. Dağıtım yöntemlerini otomatik ve manuel olarak ayırmak c. Otomatik dağıtım örneği olarak elektron-forge'un alınması, Uygulama Paketi sayfasından asar hakkında bilgi alınması ve manuel dağıtım örneği olarak kaynak dosyaların kopyalanması ve asar arşivinin oluşturulması. #### 4. HAFTA Bu hafta belge dizininin yeniden yapılandırılmasına odaklanacağız. Şunları içermektedir:
1 - Mevcut kılavuzları en az üç kategoriye ayırarak: a. Hızlı başlangıç kılavuzu b. Temel bilgileri öğrenme c. İleri düzey adımlar
Hızlı Başlangıç kategorisi, yeni kullanıcıların sıfırdan hızlı başlangıç yapmalarına olanak tanıyan tutarlı bir kılavuz serisi (yükleme, yapılandırma, dağıtım) içerir. Her kılavuz, serideki önceki/sonraki kılavuzların bağlantılarını içermelidir.
Yapı aşağıdaki gibi görünebilir: 1. Ön koşullar 2. Electron'u kurun 3. Temel bir uygulama oluşturun 4. Uygulamayı paketleyin/Dağıtın
Hızlı Başlangıç bölümünü tamamladıktan sonra kullanıcı, Electron uygulamalarının nasıl çalıştığıyla ilgili temel bilgileri edinecek ve tamamen çalışan ve dağıtılabilir bir Electron uygulamasına sahip olacaktır.
"Temelleri öğrenme" kategorisinde, Electron hakkındaki bilgileri pekiştirmeyi ve Hızlı Başlangıç bölümlerinde oluşturulan uygulamanın kapsamını genişletmeyi amaçlayan kılavuzlar içerir. Bu kılavuzlarda şunlar yer alır: - Uygulama Mimarisi - Uygulamanıza Özellik Ekleme - Ortak Kılavuzlar ve KSA'lar
Gelişmiş adımlar kategorisinde, Electron uygulamanızı yapılandırmaya ve ince ayar yapmaya yönelik daha gelişmiş kılavuzlar içerir: - Test ve Hata Ayıklama - Erişilebilirlik - Güvenlik - Güncellemeler
2 - belge sayfalarının sayısını azaltır. Dokümanların mevcut sürümü, belirli düzeyde çakışan içerik ve kategorize edilmemiş talimatlar içermektedir. Örneğin: - İlk Uygulamanızı Yazma Aşamasında Elektron Oluşturma ve Kurulumu - Uygulamanızı Paketleme ve Uygulama Dağıtımı İçin Bir Dosyaya Paketleme - Ayrıntılı ve İleri Düzey kategorilerde kategorize edilmemiş talimatlar: Öneri: Aşağıdaki belgeleri GitHub'a taşıyın ve ana dokümanlardan hariç tutun. Bu belgeler, Electron geliştirme yönergelerine özeldir ve kaynak kod deposu, bu belgelere bakacağınız ilk yerdir: - Elektron Geliştirme - Chromium Geliştirme - V8 Geliştirme - Electron'daki Sorunlar - Electron Yamalar - Pull İstekleri - Kaynak Kodu Dizin Yapısı - Test - Kodlama Stili
Bu azaltmanın ana fikri, fazla miktarda kullanılabilir kılavuzu ortadan kaldırmak, dağınık bulmacalı bilgi parçalarını bir araya getirmek ve yeni katılanlara Electron dokümanlarının daha yapılandırılmış, kolay gezinilen ve kullanıcı dostu bir versiyonunu sunmaktır.
5.-7. HAFTA
5. hafta, elektron-api-demos'un ana dokümanlara nasıl entegre edileceğiyle ilgili bir şablon (yöntem) hazırlamaya ayırdı. Bu şablon aşağıdaki gibi görünebilir: 1. Ana dokümandaki "Uygulamanıza Özellik Ekleme" başlığı altında, elekron-api-demos dosyasında temsil edilen kategorileri oluşturun 2. Kategorilerin her birini gözden geçirerek demo örneklerini ana belgelere aktarın: - Kod örnekleri, kaynak kodundan veya uygulamadaki ilgili özelliğin açıklamasından alınabilir - Aktarılan her örneğin ardından ilgili açıklama gelmelidir - Her alt örnek (örneğin, "Sistemi kullan iletişim kutularının" alt öğesi olan Hata iletişim kutusu) üst kısmına aktarılmalıdır
NOT 1: Hem elekron-api-demos'ta hem de ana dokümanlarda (klavye kısayolları, sürükleme ve bırakma gibi) örnekler vardır. Bu durumda, elektron-api-demos örneğinden alınan örnek öncelikli olmalıdır ve ana belgedeki örnek yoksayılmalıdır.
NOT 2: elekron-api-demos uygulamasındaki birçok örnekte, açıklanan özelliğin veya işlevin Canlı Demo önizlemesi vardır. Bu işlev, 9-10. haftalardaki Electron Fiddle entegrasyonuna kadar yoksayılacaktır.
- Yeni örnek hiyerarşisine uygun şekilde, kullanılabilir tüm özellikleri (3. Hafta'da oluşturulan) listeleyen sayfayı güncelleyin.
6. ve 7. hafta, elekron-api-demos örneklerini yukarıda açıklanan şablona göre ana belgeye aktarmaya ayrılmıştır. Son adım olarak, elekron-api-demos deposu silinmeli veya kullanımdan kaldırılmalıdır.
8.-10. HAFTA
8. Haftada, Electron Fiddle'ın ana belgelere nasıl entegre edileceğiyle ilgili bir şablon hazırlamaya ayıracağız. Bu girişim Electron Gönüllüleri ile birlikte başlatılmış (20442 numaralı sayıdaki ayrıntıları kontrol edin). Ancak projenin düzgün şekilde sonlanması gerekiyor.
Fiddle örnekleriyle devam etmek için temel şablon aşağıdaki gibi görünebilir: 1. Ana dokümanlardan bir örnek seçin (ör. hızlı başlangıç kılavuzu). Bu noktada, dokümanlarda elekron-api-demos örnekleri de yer almalıdır; 2. Örneği Electron Fiddle'da yeniden oluşturun (başlangıç noktası olarak örnek kodu veya kaynak kodunu kullanarak); 3. Fiddle'ı yerel olarak bir klasöre kaydedin; 4. Örneği /docs/fiddles/[KATEGORİ]/[BÖLÜM]/[DEMO] konumuna taşıyın. * Tamamlanan örneklerin listesi, sorunun "Demo listesi" bölümünde açıklanmıştır. 5. 2848 numaralı sorundaki ilk yorumda açıklandığı gibi "Fiddle'da başlat" düğmesini ekleyin.
9. ve 10. haftalar, yukarıda açıklanan şablona göre elektron-api-demos örneklerinin (daha önce Fiddle'a dönüştürülmüştür) ana dokümanlara entegre edilmesine ayrılmıştır.
11. HAFTA
Bu hafta, yalnızca elekron-api-demos deposu ve Electron Fiddle örneklerinin başarılı bir şekilde taşınmasının ardından proje yazma projesinin sonlandırılmasına odaklandık. Buna şunlar dahildir: - mevcut tüm kod örneklerinde "Fiddle'da başlat" düğmesinin olup olmadığını kontrol etme - mevcut tüm kod örneklerinin Fiddles olarak düzgün bir şekilde çalışıp çalışmadığını kontrol etme - ana dokümanların artık Elekron-api-demos deposuna ait olup olmadığını kontrol etme
12. HAFTA
Tamamlanan çalışmanın kesinleştirilmesi. Kabul kontrolleri.