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:
- ESLint
- Teknik yazar:
- Khawar
- Projenin 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 dokümanların kullanılabilirliğini ve faydasını da iyileştirir.
Proje Özeti Mevcut durumda ESLint'in (https://eslint.org/docs/user-guide/configuring) yapılandırma dokümanları, tek bir sayfada birçok bilgi sağlar. Sayfada başlıklar, alt başlıklar ve uygun paragraflar bulunsa da dokümanlar gözü korkutabilir. Sayfanın, belirli bir bölümle ilgilenen kullanıcıları rahatsız eden belirli bir bölümüne gitmenin yolu yoktur. Bu organizasyon eksikliği nedeniyle bilgiler de kaybolarak amacına hizmet etmeyebilir ve kullanıcılardan ekstra çaba sarf etmelerini isteyebilir.
Ancak bu sorunlar, bir dizi dikkatli adımla çözülebilir. Bu yeniden düzenlemenin ilk adımı olarak içerik denetimi yapılmasını öneriyorum. İçerik denetimi hem bilgilerin sunumundaki sorunların belirlenmesine yardımcı olur hem de içeriğin kendi eksikliklerini (ör. eski veya eksik bilgiler) vurgular. Ardından, bilgi ağını ortaya çıkarmak için Bilgi Mimarisi (IA) projesini oluşturmayı planlıyorum. Bu, bilgileri çeşitli konulara göre kümelememize ve birbiriyle 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. Daha sonra, Markdown'da bütün pakete bağlanabilir ve çapraz referans verilebilir. Bunun sonucunda, yapılandırma dokümanlarının gezinmesi ve anlaşılması 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. Linting yazılımı hakkındaki bilgilerimle aynı. edX aracılığıyla Python öğrenmeye başladığımda küçük hataların tüm kodu nasıl karıştırabileceğini merak ettim. Kodlarınızı bir şekilde test etmek ve hatalarınızın tespit edilmesini sağlamak güzel olur diye düşündüm. Sonra da "linçleme" terimini öğrendim. Henüz linçleme yazılımı kullanmadım ama bu teknolojilerin önümüzdeki günlerde hayatımı çok daha kolaylaştıracağından eminim.
Elektrik Mühendisliği geçmişim ve biraz programlama deneyimim sayesinde kodlama sorunlarını ve programcıların gereksinimlerini daha iyi anlayabiliyorum. Ayrıca, Teknik ve Mesleki İletişim bölümünden mezun olduğum için kullanıcıların hayatını kolaylaştırmaya çalışıyorum. 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. İçerikte gezinmenin kolay ve hiçbir komplikasyondan 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 bir 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ı belirleme - Yeniden yapılandırma gereksinimlerini karşılamak için gerekiyorsa belge 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 büyük olasılıkla bir veya iki unsurla ilgilenirler. Bu nedenle, kullanıcıların belirli bir ilgilendikleri konuya yönlendirilmesi ve dolayısıyla çözümü etkili bir şekilde sunması önemlidir. ESLint iç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 kişi ayrıştırıcı, ortamlar ve genel değerleri belirtme hakkındaki tartışmaları aşağı kaydırmalıdır. Bütün uygulama kullanıcıları yorar ve web sitesinden uzaklaşmalarına neden olabilir. Benzer şekilde, bir 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. Dokümanların kalitesi, ne kadar iyi hazırlanmış olursa olsun bu sorunların derhal ele alınması gerekir. Takip eden tartışmada bu ve diğer ilgili sorunlar için çözümler öneririm.
İçerik Denetimi Yapılandırma belgelerini yeniden düzenleme işleminin ilk adımı, kapsamlı bir içerik denetimi yapmaktır. Denetim, eski içerik, yineleme, eksik içerik gibi bazı temel sorunların tanımlanmasını sağlayacaktır. Sonuç olarak oluşturulan içerik denetleme e-tablosu, geri bildirimleri için yönetim ve belgeleme ekipleriyle paylaşılacaktır. Bu sayede belgeleri yapılandırıp sunmak için yeni bir strateji geliştirilebilir.
Bilgi Mimarisi Oluşturma Yapılandırma belgelerindeki bilgi ağını veya bilgi akışını anlamak için bilgi mimarisi (IA) oluşturmak değerli 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ı tanımlayarak verimli bir ağ oluşturacaktır. Örneğin, "Kuralları Yapılandırma" bölümündeki içeriğin ardından, "Satır İçi Yorumlar bulunan Kuralları Devre Dışı Bırakma"ya yönlendiren bir bağlantı gösterilebilir. Bu tür başka bağlantılar da belirlenebilir ve böylece dokümanların farklı bölümleri arasında ilişkiler oluşturulabilir.
İçindekiler İçerik denetimi ve IA, belgenin belirli bölümlerine ve alt bölümlerine yönlendiren bağlantıların olduğu ayrıntılı bir içindekiler tablosu oluşturmak 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ın 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. Belgelerin yeniden kullanılabilmesi için özel bir özen gösterilmelidir. Aksi halde bu belgeler gelecekte büyüyebilir ve değiştirilebilir.
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 belge yazmak ve düzenlemek için Atom (veya benzeri bir düzenleyici)
- Belgelerin sürüm kontrolünü sağlamak için GitHub
Ara Hedefler Teklifin sunulmasından projenin tamamlanmasına kadar aşağıdaki kesin olmayan ara hedefler projenin zamanında tamamlanmasını ve süreçteki doğru akışı koruyarak projeyi zamanında tamamlaması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 (Markdown'ın yazımı, GitHub'da işbirliği gibi) 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şimde bulunacağım.
17 Ağustos 2020 - 13 Eylül 2020: Topluluk bağ kurma Topluluk bağ kurma döneminde, mentorlar ve ilgili ekiplerle yaptığım görüşmelere göre teklifimi netleştireceğim. Gerekirse hedefleri ve ara hedefleri de düzenleyeceğim. Ayrıca daha sonra proje üzerinde çalışırken kullanılacak araçların da listesini çıkaracağım.
14 Eylül 2020 - 19 Eylül 2020: İçerik denetimi Projeye başlarken yapılandırma belgelerinin kapsamlı bir içerik denetimi gerçekleştireceğim. 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'sını oluşturacağım. Bilgi ağını anlaşılır bir şekilde sunmaya odaklanacağım. Bu, bilgi akışında iyileştirmeler yapmanıza yardımcı olur.
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ı ayrıntılarıyla açıklığa kavuşturmak için IA'yı bu aşamada analiz edeceğim. Ayrıca tüm bölümler için bir hiyerarşi oluşturarak süreçteki IA'yı iyileştireceğim.
1 Ekim 2020 - 3 Ekim 2020: Son harita İçerik denetimi ve IA'dan edindiğim bilgilerin yardımıyla, yeniden düzenlenen yapılandırma belgelerine uygulanacak son bir harita oluşturacağım. Bu kapsamlı haritada bir içindekiler tablosu, konular hiyerarşisi, bağlantılar ve belgelerdeki bölümler arasındaki çapraz referanslar listesi yer alacaktır.
4 Ekim 2020 - 5 Ekim 2020: Tartışma Bu aşamada, dokümanları düzenlemeden önce bulgularımı sunup gerekli planlamayı mentorlara ve ilgili ekiplere yapacağım. Verecekleri geri bildirimler planı daha iyi hale getirmeye 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 belgelerinin bazı bölümleri yeniden yazılabilir veya bazı yeni öğeler eklenebilir. Bu aşamada, belgelerin doğru, güncel, esnek ve yeniden kullanılabilir olmasını sağlamaya odaklanılır.
21 Ekim 2020 - 25 Ekim 2020: Düzeltmeler ve bağlantılar Bu aşamada dil bilgisi ve yapısal hatalardan kurtulmak için kendi çalışmamı gözden geçireceğim ve yaptığım çalışmaların doğruluğundan emin olmak için tekrar kontrol edeceğim. Belgelerin daha önce oluşturulan bilgi haritasına uygun olduğundan emin olmak için IA uyarınca bölümler arasında bağlantılar 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 işlem, ilk taslağın eksiksiz 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. Onlardan geri bildirim alacak ve yapılması gereken düzenlemelerin listesini oluşturmak üzere fikirlerimi tartışacağım.
6 Kasım 2020 - 12 Kasım 2020: İlk düzenlemeler Mentorların geri bildirimlerinin yardımıyla dokümanların ilk taslağını düzenleyeceğim. Asıl düzenlemeler yorumların ve geri bildirimlerin doğasına bağlı olacaktır. Ancak düzenleme aşamasının odak noktası tekrar kullanım, doğruluk ve esneklik gibi 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üzenlemeler üzerinde odaklanılacak ve düzenleme sürecinde ortaya çıkmış olabilecek diğer 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, son şeklini vermek üzere mentorlarla görüşülecek. Bu aşamanın tamamlanmasıyla birlikte dokümanlar son hallerini alarak web sitesine ve GitHub deposuna yüklenmeye hazır hale gelir.
20 Kasım 2020 - 23 Kasım 2020: Web sitesinde 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 sorunlarla uygun şekilde ilgilenilecektir.
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 raporuna dahil edilir. 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 proje raporu mentorlara gönderilecek. Mentorlar ve ilgili ekiplerle toplantı/konuşma yoluyla projenin tamamı incelenecek.
Proje boyunca mentorlara danışarak değerli geri bildirimleri almayı sürdüreceğim. Tüm bu ara hedefler, topluluk bağ kurma ve teklif inceleme dönemlerinde mentorlarla yapacağınız görüşmelere bağlı olarak değiştirilebilir.
Hakkımda Elektrik Mühendisliği alanında lisans derecem ve Kuzey Carolina Devlet Üniversitesi'nden Teknik ve Profesyonel İletişim alanında lisans derecem var. 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. Bir online yayında (Global Village Space) alt editör olarak ve Duke Üniversitesi'nde Duke Forge'da İletişim Stajyeri olarak çalıştım. Bunların yanı sıra yaratıcı yazarlığa da ilgim var.