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:
- ESLint
- Teknik yazar:
- Khawar
- Proje adı:
- Yapılandırma Dokümanlarını Yeniden Düzenleme/Yeniden Yazma
- Proje uzunluğu:
- Standart uzunluk (3 ay)
Proje açıklaması
Soyut
Bu projenin amacı, ESLint için yapılandırma belgelerini yeniden yapılandırmak ve etkili bir bilgi mimarisi oluşturmaktır. Bu sayede gezinme kolaylaşır ve dokümanların kullanılabilirliği ve yararlılığı artar.
Proje Özeti Mevcut durumda ESLint'in yapılandırma dokümanları (https://eslint.org/docs/user-guide/configuring), tek bir sayfada çok fazla bilgi sağlıyor. Sayfada başlıklar, alt başlıklar ve uygun paragraflar bulunmasına rağmen dokümanlar çok fazla bilgi içerebilir. Sayfanın belirli bir bölümüne gidilemez ve bu durum, belirli bir bölümle ilgilenen kullanıcılar için can sıkıcı olabilir. Bu düzensizlik nedeniyle bilgiler kaybolabilir, amacına ulaşamaz ve kullanıcılardan ek çaba göstermelerini isteyebilir.
Ancak bu sorunlar, dikkatli bir şekilde uygulanacak bir dizi adımla çözülebilir. Bu yeniden yapılanmanın ilk adımı olarak bir içerik denetimi yapmanızı öneririm. İçerik denetimi, yalnızca bilgilerin sunumuyla ilgili sorunları belirlemenize yardımcı olmakla kalmaz, aynı zamanda içeriğin eksikliklerini (ör. eski veya eksik bilgiler) de vurgular. Daha sonra, bilgi ağını ortaya çıkarmak için Bilgi Mimarisi'ni (IA) oluşturmayı planlıyorum. Bu sayede bilgileri çeşitli konulara göre kümeleyebilir ve birbiriyle yakından ilgili konular arasındaki bağlantıları bulabiliriz. Bu iki uygulamadan elde edilen analizler, tek sayfalık dokümanları birden fazla sayfaya bölmek için kullanılır. Ardından, Markdown'da tüm pakete bağlantı verilebilir ve çapraz referans yapılabilir. Sonuç olarak, yapılandırma dokümanlarının daha düzenli ve gezinmesi ve anlaşılması daha kolay bir sürümü olacak.
Motivasyon Açık kaynak yazılımı uzun süredir kullanıyor olsam da bu terim hakkındaki bilgim, Linting yazılımı hakkındaki bilgime benzer şekilde oldukça yeni. Python'u (edX üzerinden) öğrenmeye başladığımda, küçük hataların nasıl tüm kodu bozabileceğini merak ediyordum. Kodlarınızı bir şekilde test etmenin ve hatalarınızın belirlenmesinin güzel olacağını düşündüm. Sonra da "linting" terimini duydum. Henüz uygun biçimde kod yazma yazılımı kullanmadım ancak bunların, önümüzdeki günlerde hayatımı çok daha kolaylaştıracağından eminim.
Elektrik Mühendisliği eğitimim ve programlama konusundaki deneyimim sayesinde kodlamayla ilgili sorunları ve programcıların ihtiyaçlarını daha iyi anlayabiliyorum. Ayrıca, Teknik ve Profesyonel İletişim alanındaki yüksek lisans derecem, kullanıcıların savunucusu olmamı ve insanların hayatını kolaylaştırmaya çalışmamı sağlıyor. Becerilerim ve uzmanlığım bu proje için iyi bir kombinasyon olacak ve ESLint belgelerine değer katacak.
Hedefler Bu projenin genel hedefi, ESLint'in yapılandırma sayfasındaki belgelerin kolay anlaşılır olmasını ve kullanıcıları bunaltmamasını sağlamaktır. İçerikte gezinmenin kolay ve karmaşıklıktan uzak olması projenin başarısı için önemlidir. Projenin önemli hedefleri şunlardır. - Kapsamlı bir içerik denetimi gerçekleştirme - Bilgi akışını anlamak için bir bilgi mimarisi oluşturma - Dokümanları yeniden düzenlemek için bilgi mimarisini iyileştirme - İçeriğin farklı bölümleri arasındaki bağlantıları ve referansları belirleme - Yeniden yapılandırma koşullarını karşılamak için gerekirse dokümanların bölümlerini yeniden yazma/düzenleme
- İçeriğin esnek ve yeniden kullanılabilir olduğundan emin olun
Proje Açıklaması ESLint yapılandırması, ESLint'i özelleştirilebilir hale getiren önemli bir özelliktir. Yapılandırmayla ilgilenen kullanıcılar, belirli bir zamanda kesinlikle bir veya iki konuyla ilgilenir. Bu nedenle, kullanıcıların ilgilendikleri konuya yönlendirilmesi ve böylece çözüme etkili bir şekilde yönlendirilmesi önemlidir. ESLint için yapılandırma dokümanlarının mevcut durumu, birçok yararlı bilgi içerir ancak kullanıcıların bunalmış, bıkkın ve kaybolmuş hissetmelerini sağlayacak şekilde düzenlenmiştir. Örneğin, ESLint'te üçüncü taraf eklentilerinin kullanımı hakkında bilgi edinmek isteyen bir kullanıcının, ayrıştırıcı, ortamlar ve genel değişkenleri belirtmeyle ilgili tartışmayı geçerek sayfayı aşağı kaydırması gerekir. Bu uygulamanın tamamı kullanıcılar için yorucudur ve onları web sitesinden uzaklaştırmalarına neden olabilir. Benzer şekilde, sayfanın ortasında olan bir kullanıcı belirli bir bölüme gitmek veya yalnızca benzer konulara göz atmak istiyorsa bu kullanıcılar için bu tür bir yardım sağlanmadığından bu işlem kolay olmayacaktır. Ne kadar iyi hazırlanmış olursa olsun, dokümanların kalitesi kullanışlılığına bağlı olduğundan bu sorunlara hemen dikkat edilmesi gerekir. Aşağıdaki tartışmada bu ve ilgili diğer sorunlara yönelik çözümler öneriyorum.
İçerik Denetimi Yapılandırma belgelerini yeniden düzenleme sürecinin ilk adımı, kapsamlı bir içerik denetimi gerçekleştirmektir. Denetimde, güncel olmayan içerik, kopya içerik, eksik içerik gibi bazı önemli sorunlar tespit edilmeye çalışılır. Sonuç olarak oluşturulan içerik denetimi e-tablosu, geri bildirim almaları için yönetim ve dokümanlar ekipleriyle paylaşılır. Bu, dokümanları yapılandırma ve sunma konusunda yeni bir strateji geliştirmenize yardımcı olur.
Bilgi mimarisi oluşturma Bilgi ağını veya yapılandırma dokümanlarında bilgi akışını anlamak için bilgi mimarisi (IA) oluşturmak yararlı olabilir. İçerik denetiminin bulguları, bilgi akışını anlamak ve geliştirmek için iyi bir temel oluşturur. Ardından 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ş Ulaşım yalnızca mevcut içeriği yeniden yapılandırmakla kalmayacak, belgenin çeşitli bölümleri arasındaki bağlantıları ve çatalları da tanımlayacak ve böylece verimli bir ağ oluşturacaktır. Örneğin, "Kuralları Yapılandırma" bölümündeki içeriğin ardından "Satır İçi Yorumlarla Kuralları Devre Dışı Bırakma" bölümüne yönlendiren bir bağlantı bulunabilir. Bu tür başka bağlantılar da tanımlanabilir. Böylece dokümanların farklı bölümleri arasında ilişkiler oluşturulabilir.
İçindekiler tablosu: İçerik denetimi ve içerik analizi, dokümanların belirli bölümlerine ve alt bölümlerine yönlendiren bağlantılar içeren ayrıntılı bir içindekiler tablosu oluşturmak için yeterli bilgi sağlar. 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 belgelerine ulaşan kullanıcılar için bir içindekiler tablosu oluşturulabilir. Böylece, kullanıcıların web sitesindeki yolculuklarına yardımcı olabilirsiniz. İçindekiler tablosu, kısa ancak kapsamlı olması için tüm birinci ve ikinci düzey başlıkları içerebilir. Örneğin, Prettier (https://prettier.io/docs/en/index.html) tarafından belgeleri düzenlemek için kullanılır.
Basit ve düzenli bir yapı oluşturmak için tüm dokümanlar Markdown kullanılarak oluşturulacak. Gelecekte büyüyüp değişebileceği için dokümanların yeniden kullanılabilir olması için özel özen gösterilir.
Kullanılacak Araçlar Proje üzerinde çalışırken kullanışlı olabilecek bazı önemli araçlar - IA gerektiğinde çizimler oluşturmak için 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ğıdaki geçici ara hedefler, projenin zamanında tamamlanmasını ve süreçte doğru akışı sağlamasını sağlar.
10 Temmuz 2020 - 16 Ağustos 2020: Teklif inceleme ve seçim ESLint dokümanlarını inceleyip projeyi tamamlamak için gereken becerileri (ör. Markdown yazma, GitHub'da ortak çalışma) geliştireceğim. Ayrıca GitHub üzerinden belgelere katkıda bulunacağım ve belgeleri daha iyi anlamak için diğer kişilerle iletişim kuracağım.
17 Ağustos 2020 - 13 Eylül 2020: Toplulukla bağ Toplulukla bağ kurma dönemi boyunca, danışmanlar ve ilgili ekiplerle görüşmelere göre teklifimi geliştireceğim. Gerekirse hedefleri ve aşamaları da düzenleyeceğim. Ayrıca, projede çalışmak için kullanılacak araçları kısa listeye alacağım.
14 Eylül 2020 - 19 Eylül 2020: İçerik denetimi Projeye başlamak için yapılandırma dokümanları üzerinde kapsamlı bir içerik denetimi yapacağım. Amaç, içerik ve sunumuyla ilgili sorunları vurgulamaktır.
20 Eylül 2020 - 25 Eylül 2020: Bilgi Mimarisi (IA) İçerik denetiminden sonra yapılandırma belgelerinin IA'sini oluşturacağım. Bilgi ağını anlaşılır bir şekilde sunmaya odaklanacağım. Bu sayede, bilgi akışında iyileştirmeler yapabilirsiniz.
26 Eylül 2020 - 30 Eylül 2020: Bağlantılar ve referans Belgenin çeşitli bölümleri arasındaki bağlantıları ve referansları ayrıntılarıyla belirtmek için bu aşamada IA analiz edeceğim. Ayrıca tüm bölümler için bir hiyerarşi oluşturarak süreçteki bilgi erişimini iyileştireceğim.
1 Ekim 2020 - 3 Ekim 2020: Nihai harita İçerik denetimi ve bilgi analizi aracılığıyla elde edilen analizlerin yardımıyla, yeniden düzenlenen yapılandırma dokümanlarına uygulanacak nihai bir harita oluşturacağım. Bu kapsamlı haritada bir içindekiler tablosu, bir konu hiyerarşisi ve dokümanların bölümleri arasındaki bağlantıların ve çapraz referansların bir listesi yer alacaktır.
4 Ekim 2020 - 5 Ekim 2020: Tartışma Bu noktada, yani dokümanları düzenlemeden önce, bulgularımı ve planımı mentorlara ve ilgili ekiplere sunacağım. Geri bildirimleri, planı hassaslaştırmaya ve gerektiğinde değişiklikler yapmaya yardımcı olur.
6 Ekim 2020 - 20 Ekim 2020: Yeniden yazma ve düzenleme Bu dönemde, dokümanların üzerinde çalışılması gereken bölümleri düzenleyip güncelleyeceğim. Yapılandırma dokümanının bazı bölümleri yeniden yazılabilir veya yeni bilgiler eklenebilir. Bu aşamada odak noktası, belgelerin doğru, güncel, esnek ve yeniden kullanılabilir olmasını sağlamaktır.
21 Ekim 2020 - 25 Ekim 2020: Düzeltmeler ve bağlantılar Bu aşamada, dil bilgisi ve yapısal hataları gidermek ve ayrıca doğruluğunu kontrol etmek için kendi çalışmamı inceleyeceğim. Ayrıca, belgelerin daha önce hazırlanan bilgi haritasına uygun olmasını sağlamak için, bölümler arasına bağlantı ve referanslar da ekleyeceğim.
26 Ekim 2020 - 31 Ekim 2020: Gönderim için son sürüm Tüm Markdown dosyalarını bağlayacağım, bir içindekiler tablosu oluşturacağım ve taslakları mentorlarla paylaşacağım. Bu, ilk taslağın eksiksiz bir paket halinde gönderilmesi için kullanılır.
1 Kasım 2020 - 5 Kasım 2020: İlk inceleme Bu beş gün boyunca ilk taslağı danışmanlarımla tartışacağım. Geri bildirimlerini alacağım ve yapılması gereken düzenlemelerin listesini oluşturmak için fikirlerimi onlarla tartışacağım.
6 Kasım 2020 - 12 Kasım 2020: İlk düzenlemeler Mentorların geri bildirimlerinden yararlanarak dokümanların ilk taslağını düzenleyeceğim. Asıl düzenlemeler yorumların ve geri bildirimlerin niteliğine bağlı olsa da yeniden kullanım, doğruluk ve esneklik amaçları, düzenleme aşamasının temelini oluşturur.
13 Kasım 2020 - 15 Kasım 2020: İkinci inceleme İlk düzenlemelerin tamamlanmasının ardından ilerleme durumu, mentorlarım ve ilgili ekiplerle bir kez daha tartışacağım. Bu görüşmelerde, ilk sürümde yapılan düzenlemelere odaklanılır ve düzenleme sürecinde ortaya çıkmış olabilecek diğer sorunlar da vurgulanır.
16 Kasım 2020 - 19 Kasım 2020: İkinci düzenlemeler Ardından dört gün boyunca dokümanı düzenleyeceğim. Sonuç olarak üretilen sürümler, nihai şeklini vermek için mentorlarla görüşülür. Bu aşama tamamlandığında belgeler, web sitesine ve GitHub deposuna yüklenmeye hazır olacak.
20 Kasım 2020 - 23 Kasım 2020: Web sitesine yükleme Gerekli tüm düzenlemeler yapıldıktan sonra belgeler web sitesine yüklenir. Dokümanlar üzerinde çalışmamız için birkaç gün daha süremiz olduğu için süreçte karşılaşılan tüm sorunlar uygun şekilde ele alınacaktır.
24 Kasım 2020 - 28 Kasım 2020: Proje raporu Bu beş günlük süre içinde projenin ayrıntılı bir raporu oluşturulur. Hedefler, zorluklar, sorunlar ve sunulan çözümler proje raporunun bir bölümünü oluşturur. Rapor, geri bildirim için mentorlarla paylaşılır.
29 Kasım 2020 - 30 Kasım 2020: Nihai gönderim Proje, tüm dosyalarla birlikte ve proje raporuyla birlikte mentorlara gönderilir. Mentorlar ve ilgili ekiplerle bir toplantı/tartışma yapılarak projenin tamamı gözden geçirilir.
Proje boyunca, değerli geri bildirimlerini almak için mentorlara danışmaya devam edeceğim. Bu aşamaların tümü, toplulukla bağ kurma ve teklif inceleme dönemlerinde mentorlarla yapılan görüşmelere göre değiştirilebilir.
Hakkımda Kuzey Karolina Eyalet Üniversitesi'nden Elektrik Mühendisliği lisans ve Teknik ve Profesyonel İletişim yüksek lisans derecesine sahibim. Teknik ve profesyonel yazım ve düzenleme, iletişim ve içerik yönetimi, web ve mobil kullanılabilirlik çalışmaları ve talimat tasarımı alanlarında deneyim sahibiyim. Bir online yayında (Global Village Space) alt editör ve Duke Üniversitesi'nde Duke Forge için iletişim stajyeri olarak çalıştım. Bunların yanı sıra yaratıcı yazarlıkla da ilgileniyorum.