Mevcut aşama:
Dökümanlar Sezonu 2019 programı 6 Mart 2020'de sona erdi. Zaman çizelgesini inceleyin.
Bu sayfa, bu yılın Dokümanlar Sezonu için çalışmalarınızı bitirdiğinizde proje raporunuzu nasıl oluşturacağınızla ilgili teknik yazarlar için yönergeler içerir.
Proje raporunuzu gönderme
Projenin kesinleşme aşaması açıldığında, teknik yazar kılavuzunun proje tamamlama bölümünde bulunan formu doldurarak proje raporunuzu gönderebileceksiniz.
Proje raporuna dahil edilecek bilgiler
Bu bölümde proje raporunuzda sağlayabileceğiniz bilgi türleri açıklanır. Proje raporu formunda serbest metin alanları ve çoktan seçmeli sorular yer alır.
Çalışmanızın bağlantısı
Yaptığınız çalışmanın açıklamasına yönlendiren bir bağlantı sağlayın.
Bağlantı yapılan çalışmanın kısa bir açıklamasını, açık kaynak projenin kendi deposuyla birleştirdiği belgeleri, projenin mevcut durumunun özetini ve zorlukların ve öğrenilenlerin listesini içeren bir belgeye yönlendirmelidir.
Bağlantı, web sitesinde yayınlanan Dokümanlar Sezonu sonuçlarında görünür. Yayınlanan sonuçlar, program sırasında tamamladığınız çalışmayı gösterir. Yayınlanan sonuçlar, çalışmanıza öz geçmişinizin bir parçası olarak göz atmanın da harika bir yoludur.
Proje raporunuzu göndermeden önce bağlantınızı mentorunuzla paylaşmalı ve inceleme talep etmelisiniz.
Proje raporunuz için gereksinimler
Aşağıdaki koşulları göz önünde bulundurun:
- Bağlantılı içerik, Dokümanlar Sezonu sırasında tamamladığınız çalışmaları, yani yaptığınız değişiklikleri veya yazdığınız yeni dokümanları belirlemeyi kolaylaştırmalıdır.
- Çalışma sabit bir konumda olmalıdır. Gönderimden sonra URL'yi değiştiremezsiniz.
Başka bir kişi, çalışmanızı geliştirmek için bağlantının hedefindeki (veya referans verilen) içeriği kullanabilir.
- Çalışmanız% 100 tamamlandıysa başkaları tarafından kullanılabilir.
- İşiniz% 100 tamamlanmamışsa yapılması gerekenlerin açık olması gerekir.
Çalışmanızı nasıl açıklayacağınıza dair iyi örnekler
Bunların hepsini (veya herhangi birini) yapmanız gerekmez, ancak gereksinimleri karşılayabileceğiniz bazı yöntemler şunlardır:
Yaptığınız çalışmaları açıklayan bir blog yayını veya web sayfası ya da herkese açık bir GitHub gist'i oluşturun. Ayrıca, yaptığınız taahhütlerin ve üzerinde çalıştığınız depoların bağlantılarını ekleyin. Projede hâlâ yapılacak işler varsa o çalışmayla ilgili bir açıklama ekleyin. Öne çıkan veya zorlu kısımları da paylaşabilirsiniz.
Bu en iyi seçenektir çünkü birçok bilgiyi kolayca eklemenize olanak tanır. Bu iyi bir özelliktir, çünkü yaptığınız çalışmayı açıkça gösterir ve başkalarının katkınızı kullanmasını ve anlamasını kolaylaştırır.
GitHub kullanıyorsanız ve tüm çalışmanız tek bir pull isteği kapsamındaysa bu bağlantıyı kullanabilirsiniz.
- Pull isteği açıklamasının ayrıntılı olduğundan emin olun.
- Açıklamada, çalışmanın Dokümanların Sezonu için yapıldığı açıkça belirtilmelidir.
- Dokümanlar Sezonu sona erdikten sonra pull isteği üzerinde daha fazla işlem yapılması gerekiyorsa son Dokümanlar Sezonu kaydetmesinde bu gerçeğin belirtildiğinden emin olun.
- Bu proje raporu sunma yöntemi; değişiklik günlüğü, kayıtların listesi ve inceleme yorumlarının tamamını tek bir yerde bulundurma avantajına sahiptir.
GitHub deponuz Dokümanlar'ın Sezonu için tek amaçlıysa çalışmanızın ayrıntılarını içeren bir BENİOKU dosyası ekleyin.
Google Drive'da bir ortak klasör oluşturun ve oluşturduğunuz tüm yamaları dahil edin.
Google E-Tablolar ile herkese açık bir e-tablo oluşturun ve tüm kayıtlarınızı listeleyin.
Herkese açık bir sorun izleyicide, çalışmanıza ve diğer uygun şeylere açık referanslar içeren tek bir soruna bağlantı verin. Sorun yaptığınız tüm çalışmaları izlemelidir. Sorunun tüm kayıtları listelediğinden veya kaydetmeleri başka bir şekilde kolayca bulabileceğinden emin olun.
Değişikliklerinizin birleştirilmiş veya bağlam farkına bağlantı verin. Başkalarının işine yaraması için teknik yazı projenizin adını ve kim olduğunuzu içeren bir başlık eklediğinizden emin olun.
Çalışmanızı nasıl açıklayacağınıza dair yanlış örnekler
Aşağıdakileri yapmayın:
- Projenin kaynak kodunun tamamını veya çalışma dizininizi içeren bir tarball ya da zip dosyasına bağlantı oluşturun.
- Projenin birincil kaynak deposunun üst kısmına bağlantı. Örneğin, cpython üzerinde çalışıyorsanız şu bağlantı faydalı olmaz: https://github.com/python/cpython.
- Projenizin kaynak deposu klonunuza bağlanın. Bu durum, yaptığınız değişikliklerin neler olduğunu görmenizi zorlaştırır çünkü çalışmanız başka kişilerin çalışmalarıyla karışık şekilde kullanılır.
- Dokümanlar Sezonu web sitesinde proje açıklamanızın bağlantısını oluşturun.
Mentorlar için
Lütfen teknik yazarınızın uygun bir proje raporu oluşturmasına yardımcı olun. Bunu teknik yazarın çalışmasıyla ilgili kendi değerlendirmenizi oluşturmadan önce yapmanız önemlidir.
Aşağıdakileri kontrol edin:
- Gönderim, yukarıda açıklanan şartları karşılamalıdır.
- Gönderim; yapılan çalışmanın bir açıklamasını, yerine getirilen gereklilikleri ve alınan belirli kararların nedenlerini içermelidir.
Dokümanlar Mevsimi'nin amacı, teknik yazarların çok sayıda belge bir araya getirmesi değildir. Çalışmanın, barındırmaya yönelik açık kaynak projesi için faydalı olabileceği önemlidir.