Dokümantasyon Okurken Kaybolmak

İnsan doğası gereği kompleks bir varlıktır. Belki çoğumuz için basit cevapları olan bazı problemler, çoğu zaman incelenmesi gereken tonlarca neden ile beraber gelir. Sorunlara çözüm aramak isteyen ciddi insanların belki de ilk adımları kendi önyargılarını, bilgi eksikliklerini, kabiliyetlerini tanımak olmalıdır. Dökümantasyonları nasıl okumalıyız sorusunu cevap aradığımız bir yazıda, bu kadar geriden başlanmasına şaşırmış olabilirsiniz. Hayatımda ne zaman basit ve yüzeysel cevaplar arasam, bu cevaplar tarafından hazırlıksız bir şekilde hep yarı yolda bırakıldım. Sorunun kaynağına inmediğim her zaman, beklemediğim yerlerden başka sorunlar çıkmaya başladı karşıma. Sonra yorulmuşluk ve bıkmışlık içinde buldum kendimi. İşte biraz geriden başlamam bundan dolayı. Symtompları çözmekle problemlere derman olunmuyor. Elimizden geldiğince sorunun kaynağına inmek lazım. Derin sular buralar belki. Çok karanlık ve güneş almıyor. Ama asıl hazineler hep burada yatıyor. Neyse, hadi bakalım elimizden geldiğince beraber düşünelim.

Dökümantasyon okurken, insanın kaybolması “Okuduklarını bir yerden sonra anlamamaya başlaması ve anlasa bile bir önceki kısımlar ile bağlantılarını kuramıyor olması” şeklinde özetlenebilir. Ama insanın bir yazıyı anlamaması sebeplerinin başında:

1. Konu ile alakalı temel bilgilere sahip olmamak. Anlamadığınız kısımlara neden olan kavramları çok geçiktirmeden öğrenmede yarar var.
2. Fiziksel sorunlar. Mesela uykunuzu iyi alamamış olmanız ve yorgunken okumaya çalışmanız. Bir de bazı insanların zihinlerinin açık olduğu belli zaman ve şartlar vardır. O zamanlar dışında okunan kitaplar çok akılda kalmayabiliyor.
3. Öğrenilen konu ile alakalı yeteri kadar heyecanlı ve meraklı olmamak. Bir konuyu öğrensem de olur öğrenmesem de şeklinde okursanız, genelde sonuç ikinci tarafa doğru kayar. Sanki öğrenip başka insanlara anlatacaksınız ve onların sorularını cevaplayacaksınız heyecanı ve beklentisi ile okuyun. Onların soracağı soruları siz kafanızdan öncelikle kendinize sorun ve sanki o insanlara anlatıyorsunuz gibi konuyu basitleştirmeye çalışın. Çok faydasını göreceksiniz.
4. Doğru okuma tekniklerine sahip olmamak. Mesela okurken, hiç sorular soruyor musunuz? Kısa notlar alıyor musunuz? Bazı insanlar okudukları yazılar arasındaki ilişkileri zihinlerinde daha rahat kurabiliyorlar ve dolayısıyla digital bir ortamda rahat okuyabiliyorlar. Ama belki sizin için bir dökümantasyonun çıktısını almak ve kalem ile notlar alarak okumak daha doğru bir çözüm olabilir. Ya da dijital ortamlarda stylus gibi bir çözüm kullanabilirsiniz.
5. Teknik konuları roman gibi yüzeysel okumak. Teknik yazılarda öyle yerler olur ki konunun omurgası gibidir. Orayı atlarsanız, olay biter. Neden soruları altında boğulmaya başlarsınız.
6. Zihninizi karmaşık materyalleri anlayacak şekilde yetiştirmemiş olmak. Zihin de aslında bir sporcunun kasları gibidir. Çalıştıkça daha güçlenir. Daha hızlı ilişkiler kurmaya başlar. Soyut kavramları daha hızlı anlar.
7. Submissive bir tarzda okumak. Bu, yazar ne derse kabulümdür tarzı ile okumaktır özetle. Ama bu bir problem. Tamam, yazarın yazdıkları büyük bir ihtimal doğrudur. Ama submissive tarzda okuduğunuzda, zihin heyecanlanmıyor. Bakın kendinize; kızdığınız anları, korktuğunuz anları, çok mutlu zamanlarınızı nasıl da hatırlıyorsunuz… Ama nerede sıradan günler zihninizin anı defterinde? Zihin savaşacak bir düşman gördüğünde heyecanlanıyor, gardını alıyor ve okuduğunuz her cümle bir düşman oluyor savaşıyorsunuz onunla. Kendinizi konunun uzmanı olarak hissedin ve bu şekilde okuyun. O zaman kafanıza ne kadar da çok soru geldiğine şaşıracaksınız.
8. Okunan konuda her bir sonucun nedenlerine çok takılmak. Bunun yararı kişiden kişiye değişebiliyor. Bazı insanların ise bazı kısımları oldukları gibi kabul edip öğrenmelerine devam etmeleri gerekiyor. Genelde nedenlere takılmak ve cevaplar aramak uzman mühendisler için yararlı oluyor, çünkü bu mesleğe yeni başlayanlara göre daha çok şey bildiklerinden nedenlere takılıp cevaplar aramaları, kendilerini çok yavaşlatmayabiliyor. Bazen insan “Demek ki böyle çalışıyor” diyerek konuyu öğrenmeye devam etmeli. Sonra yeniden aynı kısımlar gözden geçirilip daha detaylı öğrenilebilir. Biraz da tabi kişisel kabiliyetlere kalmış.
9. Okuduğunuz ortam okumaya uygun mu? Herkes sesli ortamlarda okumaya alışkın olmayabilir. Belki de sessiz bir ortamda sıcak bir içecek ile okumayı denemelisiniz. Amaç, ne kadar zihninizi açabilirseniz, o kadar faydasını göreceğiniz gerçeği.

Bunlar temel olarak gördüğüm bazı sorunlar.

Doğru yazılmış official bir documentation genel olarak API Reference ve Developer Guide gibi kısımlara sahiptir. Uzun vadeli referans kaynağı API referanslarıdır. Bunlar hangi methodun ve sınıfın ne yaptığını anlatır. Zaten bu kısım, kullandığınız IDE destek veriyorsa, kod autocomplete edildiğinde bir tooltip içinde size gösterilecektir. API referensaları öğrenilmek istenilen sınıfın temsil ettiği ana konu hakkında da detaylı bilgiler verebilirler.

İlk başlayan için teknolojiyi öğretecek olan developer guide’lardır. Developer guide, konuyu daha bütüncül olarak ve bilmeyen bir insanın anlayacağı şekilde adım adım anlatır. Konular daha topludur ve ilişkiler navigation linkleri ile ayrılmıştır. Çoğu insan bu navigation linklerini önemsemez. Halbuki aşağıdaki nedenlerden dolayı çok önemlidirler:

1. Anlatılan başlıklar arasında ki ilişkileri burada görürsünüz. Alakalı konular bir başlık altında toplanır.
2. Eğer dökümantasyon navigasyonu doğru bir şekilde anlaşılırsa, öğrenilmek istenilen konu daha hızlı bulunabilir.

Mesela, aşağıda Android Dev Guide’nın navigation linklerinden bir parça görülebilir:

Orada ki linklerin sırası bile önemlidir. Öğrenilecek konunun navigation linklerine bilinçli bir şekilde göz geçirin! Orası kullanılan terminolojiyi görmeninde en hızlı yoludur aynı zamanda.

Bir teknoloji öğrenecekseniz, onun geleceği hakkında ki kararlarınızı documentation’larını nasıl yazdıklarına göre de verebilirsiniz. Burada ufak bir not düşeyim: Şimdiye kadar en çok beğendiğim dökümantosylar Google tarafından hazırlamış oluyor: Angular, Android, Firebase…

Genelde büyük kaynaklara sahip projeler kendi technical writer’larını işe alırlar ve bu insanlarla teknik konuları yazılımcıların rahatlıkla anlayacağı şekilde yazarlar. Örneğin Android development guide’larına bakarsanız, konuları teker teker anlattıklarını görürsünüz. İlk olarak genel bir bilgi verirler. Sonrasında her bir building block denilen ana parçalar hakkında detaylı bilgiler vermeye başlarlar ve bunlar arasında da anlatım genelden daha özel ve daha detaylı kısımlara doğru olur. Bu güzel bir dökümantasyon hazırlama şeklidir. Aynı zamanda konu örnekler ile akla indirgenir ve soyut ifadeler somutlaşmaya başlar.

Dökümantasyon okunma sırasında ki en büyük sorunlar iki nedenden gelir:

1. Development guide’ları yeteri kadar okumadan direk koda girmek.
2. Hiç kod yazmadan uzun bir zaman boyunca development guide okumak.

Doğru olan ise orta yolda kalmaktır. Bu da bir sistemin ana building block’ları hakkında genel bilgilere sahip olmak, öğrenilecek teknolojinin genel mimarisini okumak ve yavaşça koda dalmaktır. Bu süreçte development guide okunmaya devam edilir. İlk okumalar bir kaç gün hatta bir hafta ve biraz daha sürebilir ve sonrasında koda başlanabilir. Öğrenme sürecinin en etkili olduğu zaman ise öğrenilen bilginin bir projede kullanılmaya başlandığı zamandır.

Eğer dökümanyon sırasında kafanız karışıyorsa, bu okuduğunuz bilgileri anlamadan daha ziyade okuduğunuz kısımlar arasında ki ilişkileri kuramıyor olduğunuzdandır. Bunun nedenleri farklılık gösterebilir. Ama çözüm olarak mind mapping kullanabilirsiniz. Aşağıda ki yazım bu konuda size yardımcı olabilir:

Etkili not almak için Mind Mapping

Bir de, evet, bazı dökümantasyonlar gerçekten kötü olabiliyor. Bunu da kabul etmek lazım. O zaman belki başka insanların yazdıkları makalelere ya da çektikleri videolara bakılabilir.

Yeni programlama dillerini nasıl hızlı bir şekilde öğrenebilirsiniz sorusuna bir kaç cevap vermeye çalıştığım bir videom vardı. Ona da bakabilirsiniz:

Bir sonra ki yazımda görüşmek üzere…