Bu sayfa, Google Dokümanlar Sezonu için kabul edilen teknik yazı projesinin ayrıntılarını içerir.
Proje özeti
- Açık kaynak kuruluşu:
- ESLint
- Teknik yazar:
- Hawar
- Proje adı:
- Yapılandırma Belgelerini Yeniden Organize Etme/Yeniden Yazma
- Proje süresi:
- Standart uzunluk (3 ay)
Proje açıklaması
Özet
Bu projenin amacı, ESLint'in yapılandırma belgelerini yeniden yapılandırmak ve etkili bir bilgi mimarisi oluşturmaktır. Bu, gezinmeyi kolaylaştırır ve ayrıca dokümanların kullanılabilirliğini ve faydasını artırır.
Proje Özeti ESLint'in yapılandırma belgeleri (https://eslint.org/docs/user-guide/configuring), şu anki haliyle tek bir sayfada birçok bilgi sağlar. Sayfada her ne kadar alt başlıklar ve uygun paragraflar bulunsa da, doküman göz korkutucu olabilir. Sayfanın, belirli bir bölümle ilgilenen kullanıcılar için sinir bozucu olan belirli bir bölümüne gitmenin yolu yoktur. Bu organizasyon eksikliği nedeniyle bilgiler de kaybolabilir, amacına hizmet edemez ve kullanıcılardan ek çaba göstermelerini isteyebilir.
Ancak bu sorunlar bir dizi dikkatli adımla çözülebilir. Bu yeniden düzenleme sürecinin ilk adımı olarak bir içerik denetimi yapılmasını öneriyorum. İçerik denetimi yalnızca bilgilerin sunulmasındaki sorunların belirlenmesine yardımcı olmakla kalmaz, aynı zamanda içeriğin eksikliklerini de (ör. eski veya eksik bilgiler) vurgular. Ardından bilgi ağını ortaya çıkarmak için Bilgi Mimarisi'ni (IA) oluşturmayı planlıyorum. Bu, bilgileri çeşitli konulara göre kümelememize ve yakından ilgili çeşitli konular arasındaki bağlantıları bulmamıza olanak tanır. Bu iki uygulamadan elde edilen analizler daha sonra tek sayfalık dokümanları birden fazla sayfaya bölmek için kullanılır. Ardından, tüm pakete bağlantı verilebilir ve Markdown'da çapraz referans verilebilir. Bunun sonucunda, yapılandırma belgelerinin, gezinmeyi ve anlamayı daha kolay olan daha düzenli bir sürümü olacaktır.
Motivasyon Uzun süredir açık kaynak yazılım kullanmama rağmen, bu terime olan aşinalığım oldukça yeni. Bu, Linting yazılımı hakkındaki bilgilerime benzer. edX ile Python öğrenmeye başladığımda çok küçük hataların tüm kodu nasıl karıştırabileceğini merak etmiştim. Kodlarının bir şekilde test edilip hatalarınızın belirlenmesini sağlamak iyi olur diye düşündüm. Sonra da "linçleme" (liting) terimini öğrendim. Henüz lintleme yazılımı kullanmadım ama bu, önümüzdeki günlerde hayatımı çok daha kolaylaştıracak.
Elektrik Mühendisliği deneyimim ve biraz programlama deneyimim sayesinde, kodlamanın sorunlarını ve programcıların gereksinimlerini daha iyi anlayabiliyorum. Ayrıca, Teknik ve Mesleki İletişim mezunu olarak hayatımı kolaylaştırmaya çalıştığım için kullanıcıları savunuyorum. Becerilerim ve uzmanlığım bu proje için iyi bir kombinasyon olacak ve ESLint belgelerine değer katacak.
Hedefler Bu projenin ana hedefi, ESLint'in yapılandırma sayfasındaki belgelerin kolay anlaşılır olmasını ve kullanıcıları bunaltmamasını sağlamaktır. İçeriklerde gezinmenin kolay ve hiçbir zorluktan arındırılmış olması projenin başarısı için önemlidir. Projenin önemli hedefleri şunlardır: - Kapsamlı içerik denetimi gerçekleştirme - Bilgi akışını anlamak için Bilgi Mimarisi oluşturma - Belgeleri yeniden düzenlemek için Bilgi Mimarisi'ni iyileştirme - İçeriğin farklı bölümleri arasındaki bağlantıları ve referansları tanımlama - Yeniden yapılandırma gereksinimlerini karşılamak için gerekirse dokümantasyonun bölümlerini yeniden yazma/düzenleme
- İçeriğin esnek ve yeniden kullanılabilir olduğundan emin olun
ESLint'in Proje Açıklaması Yapılandırması, ESLint'i özelleştirilebilir hale getiren önemli bir özelliktir. Yapılandırmayla ilgilenen kullanıcılar, belirli bir zaman için kesinlikle bir veya iki özellikle ilgilenecektir. Bu nedenle, kullanıcının ilgi duyduğu konuya yönlendirilmesi, dolayısıyla kullanıcıya etkili bir çözüm sunması önemlidir. ESLint'in yapılandırma belgelerinin mevcut durumu pek çok faydalı bilgi içermektedir, ancak kullanıcılar bunalmış, bıkkın ve kaybolmuş hissetmelerine neden olacak şekilde düzenlenmiştir. Örneğin, ESLint'te üçüncü taraf eklentilerinin kullanımı hakkında bilgi edinmek isteyen bir kullanıcı, ayrıştırıcıyı, ortamları ve genelleri belirtme hakkındaki tartışmayı aşağı kaydırmak zorundadır. Uygulamanın tamamı kullanıcılar için yorucudur ve web sitesinden uzaklaşmalarına neden olabilir. Benzer şekilde, kullanıcı sayfanın ortasında bir yerdeyse ve belirli bir bölüme gitmek veya yalnızca benzer konulara bakmak istiyorsa, kullanıcılara bu tür bir yardım sunulmadığından, bu onlar için kolay bir iş olmaz. Bir dokümanın kalitesi, ne kadar iyi hazırlanmış olursa olsun bu sorunların hemen ele alınması gerekir. Sonraki tartışmada bu ve diğer ilgili sorunlara çözümler öneririm.
İçerik Denetimi Yapılandırma belgelerini yeniden düzenleme işleminin ilk adımı, kapsamlı bir içerik denetimi yapmaktır. Denetimin amacı eski içerik, yineleme, eksik içerik gibi bazı temel sorunların tanımlanmasıdır. Sonuç olarak oluşturulan bir içerik denetim e-tablosu, geri bildirimleri için yönetim ve belge ekipleriyle paylaşılacaktır. Bu, belgeleri yapılandırmak ve sunmak için yeni bir stratejinin oluşturulmasına yardımcı olacaktır.
Bilgi Mimarisi Oluşturma Bilgi ağını veya yapılandırma belgelerindeki bilgi akışını anlamak için bilgi mimarisinin (IA) oluşturulması faydalı olabilir. İçerik denetiminin bulguları, bilgi akışını anlamak ve geliştirmek için iyi bir temel oluşturacaktır. Belgeleri daha iyi bir şekilde düzenlemek ve sunmak için IA'nın iyileştirilmiş bir sürümü oluşturulacak. Bu iyileştirilmiş IA yalnızca mevcut içeriği yeniden yapılandırmakla kalmayacak, aynı zamanda dokümanların çeşitli bölümleri arasındaki bağlantıları ve çatalları da tanımlayacak ve böylece etkili bir ağ oluşturacaktır. Örneğin, "Kuralları Yapılandırma"daki içeriğin ardından "Satır İçi Yorumlarla Kuralları Devre Dışı Bırakma"ya yönlendiren bir bağlantı görüntülenebilir. Bu tür başka bağlantılar da belirlenerek dokümanların farklı bölümleri arasında ilişkiler oluşturulabilir.
İçindekiler İçerik denetimi ve IA, belgelerin belirli bölümlerine ve alt bölümlerine yönlendiren bağlantıların yer aldığı ayrıntılı bir içindekiler tablosunun oluşturulması için yeterli bilgiyi sağlayacaktır. Her bölüm için ayrı dosyalar oluşturmak ve diğer bölümlere uygun referanslar eklemek doküman grubunun tamamına değer katabilir. Yapılandırma belgelerini açan kullanıcılar için içindekiler tablosu oluşturulabilir. Böylece kullanıcılar web sitesindeki yolculuklarına yardımcı olurlar. İçindekiler tablosu hem kısa hem de kapsamlı olması için birinci ve ikinci düzey başlıkların tümünü içerebilir. Örneğin, belgeleri düzenlemek için Prettier (https://prettier.io/docs/en/index.html) bu uygulamayı kullanır.
Tüm belgeler basit ve düzenli olması için Markdown kullanılarak oluşturulacak. Dokümanların büyüyüp değişebileceğinden, yeniden kullanılabilmesine özen gösterilecektir.
Kullanılacak Araçlar Proje üzerinde çalışırken kullanışlı olabilecek bazı önemli araçlar şunlardır: - Gerektiğinde IA için resimler oluşturmak üzere Draw.io - Markdown'da doküman yazmak ve düzenlemek için Atom (veya benzer bir düzenleyici)
- Dokümanların sürüm kontrolünü sağlamak için GitHub
Ara Hedefler Teklifin gönderilmesinden projenin tamamlanmasına kadar, aşağıda yer alan kesin olmayan ara hedefler, süreçte doğru akışı sürdürerek projenin zamanında tamamlanmasını sağlayacaktır.
10 Temmuz 2020-16 Ağustos 2020: Teklif incelemesi ve seçimi ESLint belgelerini gözden geçirip projeyi tamamlamak için gereken becerileri (ör. Markdown'ın yazımı, GitHub'da ortak çalışma) geliştireceğim. Ayrıca GitHub aracılığıyla dokümanlara katkıda bulunacağım ve dokümanları daha iyi anlamak için diğer kişilerle etkileşime geçeceğim.
17 Ağustos 2020-13 Eylül 2020: Topluluk bağı Topluluk bağ kurma döneminde, mentorlar ve ilgili ekiplerle yaptığım görüşmelere göre teklifimi hassaslaştıracağım. Gerekirse hedefleri ve ara hedefleri de düzenleyeceğim. Ayrıca proje üzerinde çalışırken kullanılacak araçları da listeleyeceğim.
14 Eylül 2020 - 19 Eylül 2020: İçerik denetimi Projeye başlarken yapılandırma dokümanlarıyla ilgili kapsamlı bir içerik denetimi gerçekleştireceğim. Hedef, içerik ve sunumuyla ilgili sorunları vurgulamaktır.
20 Eylül 2020 - 25 Eylül 2020: Bilgi Mimarisi (IA) İçerik denetiminin ardından yapılandırma dokümanlarının IA'sını oluşturacağım. Bilgi ağını anlaşılır bir şekilde sunmaya odaklanacağım. Böylece, bilgi akışında iyileştirmeler yapılabilir.
26 Eylül 2020 - 30 Eylül 2020: Bağlantılar ve referans Belgelerin çeşitli bölümleri arasındaki bağlantıları ve referansları ortaya çıkarmak için bu aşamada IA'yı analiz edeceğim. Ayrıca tüm bölümler için bir hiyerarşi oluşturacak, böylece süreçteki IA'yı iyileştireceğim.
1 Ekim 2020 - 3 Ekim 2020: Son harita İçerik denetimi ve IA'dan elde edilen bilgilerin yardımıyla, yeniden düzenlenen yapılandırma belgelerine uygulanacak son bir harita oluşturacağım. Bu kapsamlı harita, bir içindekiler tablosu, bir konu hiyerarşisi ve bir bağlantı listesi ile belgelerin bölümleri arasındaki çapraz referansları içerecektir.
4 Ekim 2020 - 5 Ekim 2020: Tartışma Bu noktada, dokümanları düzenlemeden önce bulgularımı sunacak ve planı mentorlara ve ilgili ekiplere sunacağım. Verdikleri geri bildirimler planı hassaslaştırmaya ve gerektiğinde değişiklikler yapmaya yardımcı olacaktır.
6 Ekim 2020 - 20 Ekim 2020: Yeniden yazma ve düzenleme Bu dönemde, belge üzerinde çalışma yapılması gereken bölümleri düzenleyip güncelleyeceğim. Yapılandırma dokümanlarının bazı bölümleri yeniden yazılabilir veya belgeye yeni öğeler eklenebilir. Bu aşamada, belgelerin doğru, güncel, esnek ve yeniden kullanılabilir olmasını sağlamaya odaklanılacaktır.
21 Ekim 2020 - 25 Ekim 2020: Düzeltmeler ve bağlantılar Bu aşamada, dil bilgisi ve yapı hatalarından kurtulmak ve çalışmalarımın doğruluğunu iki kez kontrol etmek için kendi çalışmamı gözden geçireceğim. Ayrıca, belgelerin daha önce oluşturulan bilgi haritasına uygun olmasını sağlamak için, IA uyarınca bölümler arasına bağlantılar ve referanslar ekleyeceğim.
26 Ekim 2020 - 31 Ekim 2020: Gönderim için son sürüm Tüm Markdown dosyalarını bağlayacağım, içindekiler tablosu oluşturacağım ve taslakları mentorlarla paylaşacağım. Bu, ilk taslağın tam bir paket halinde gönderilmesi görevini görür.
1 Kasım 2020 - 5 Kasım 2020: İlk inceleme Bu beş gün boyunca ilk taslağı mentorlarımla tartışacağım. Yapılması gereken düzenlemelerin bir listesini oluşturmak için onların geri bildirimlerini alacak ve onlarla fikirlerimi tartışacağım.
6 Kasım 2020 - 12 Kasım 2020: İlk düzenlemeler Mentorların geri bildirimlerinin yardımıyla dokümanın ilk taslağını düzenleyeceğim. Gerçek düzenlemeler yorumların ve geri bildirimlerin doğasına bağlı olacaktır ancak düzenleme aşamasının odak noktası yeniden kullanım, doğruluk ve esneklik olarak olacaktır.
13 Kasım 2020 - 15 Kasım 2020: İkinci inceleme İlk düzenlemeler tamamlandıktan sonra ilerleme durumunu mentorlarım ve ilgili ekiplerle bir kez daha tartışacağım. Bu tartışmalarda, ilk sürümde yapılan düzenlemelere odaklanılacak ve düzenleme aşamasında ortaya çıkmış olabilecek diğer tüm sorunlar vurgulanacaktır.
16 Kasım 2020 - 19 Kasım 2020: İkinci düzenlemeler Ardından, dokümanı düzenlemeye dört günlük bir süre ayıracağım. Sonuç olarak üretilen versiyonlar, mentorlarla görüşerek onlara nihai şeklini verecek. Bu aşamanın tamamlanmasının ardından belgeler son şekle sahip olacak ve web sitesine ve GitHub deposuna yüklenmeye hazır hale gelecektir.
20 Kasım 2020 - 23 Kasım 2020: Web sitesine yükleme Gerekli tüm düzenlemeler yapıldıktan sonra dokümanlar web sitesine yüklenir. Dokümanlar üzerinde çalışmak için birkaç gün süremiz olacağı için, süreçte karşılaşılan tüm sorunlar bu doğrultuda ele alınacaktır.
24 Kasım 2020 - 28 Kasım 2020: Proje raporu Bu beş günlük dönemde projenin ayrıntılı bir raporu oluşturulacak. Hedefler, mücadeleler, sorunlar ve sunulan çözümler proje raporunun bir parçasını oluşturur. Rapor, geri bildirim vermeleri için mentorlarla paylaşılacaktır.
29 Kasım 2020 - 30 Kasım 2020: Son gönderim Tüm dosyalarla birlikte proje ve rapor danışmanlara gönderilecek. Mentorlar ve ilgili ekiplerle toplantı/tartışma yoluyla projenin tamamı değerlendirilecek.
Proje boyunca değerli geri bildirimleri almak için mentorlara danışmaya devam edeceğim. Tüm bu ara hedefler, toplulukla bağ kurma ve teklif inceleme dönemlerinde mentorlarla yapılan görüşmelere bağlı olarak değiştirilebilir.
Hakkımda Elektrik Mühendisliği alanında lisans derecem, Kuzey Carolina Devlet Üniversitesi'nden Teknik ve Profesyonel İletişim bölümünden mezunum. Teknik ve profesyonel yazım ve düzenleme, iletişim ve içerik yönetimi, web ve mobil kullanılabilirlik çalışmaları ve eğitim tasarımı alanlarında deneyimim var. Online bir yayında (Global Village Space) alt editör olarak ve Duke Üniversitesi'nde Duke Forge'da İletişim Stajyeri olarak çalıştım. Bunun yanı sıra yaratıcı yazarlığa da ilgi duyuyorum.