Görevlere değil kararlara odaklanan bir yaklaşım

• Kararlara odaklanmak

  • Every Page Is Page One kitabından bir alıntı, teknik dokümantasyon yazımına yaklaşımda büyük bir değişim yarattı
  • Teknik iletişimde çoğunlukla görev desteğinden söz edilir; ancak çoğu durumda insanların bir görevi tamamlamak için ihtiyaç duyduğu bilgi, makinenin nasıl çalıştığına dair değil, karar vermeyi destekleyen bilgidir
  • Yalnızca prosedürleri belgelendirmek yeterli değildir
  • Kullanıcılara hangi kararları vermeleri gerektiğini ve bunun sonuçlarının ne olacağını anlatmalı, mümkün olduğunca onları karar vermeyi destekleyen kaynaklara ve referanslara yönlendirmeliyiz

GN⁺ Özeti

• Bu yazı, teknik dokümantasyon yazımında karar desteğinin önemini vurguluyor
• Sadece prosedürleri açıklamanın ötesine geçip, kullanıcıların daha iyi kararlar almasına yardımcı olmak gerekiyor
• Teknik yazarlar için, kullanıcıya ihtiyaç duyduğu bağlamı ve bilgiyi sağlamak önemli
• Benzer işlevlere sahip sektördeki projeler arasında Confluence ve Notion öneriliyor

[GN⁺]

Hacker News yorumları

• Alman bürokrasisi hakkında yazıyorum ve bu yaklaşıma tamamen katılıyorum.
  Rehberlerimin çoğu “Bu nedir, kim yapmalı, neden yapmalı?” diye başlar. İnsanların doğru şeyi doğru nedenlerle yaptığından emin olmalarını sağlamazsanız, tamamen yanlış bir yöne çok fazla ilerleyebilirler.
  Çoğu kamu sitesi bunu açıklamaz; sadece kendi sorumluluklarındaki prosedürü bitirmek için gerekenleri ister. Bunu daha büyük bir kararın parçası olarak görmez, kullanıcının ne yaptığını zaten bilerek geldiğini varsayar.

  • Son paragrafla ilgili olarak, UK gov sitesi bu işi çok iyi yapıyor. Prosedürü açıklayan bir açılış sayfası var; uyarılar ve dikkat edilmesi gerekenler geldikten sonra ancak asıl formu doldurabiliyorsunuz.
    Ehliyet yenileme için Google sonucu olan https://www.gov.uk/renew-driving-licence sayfasında “Start Now”a basarsanız ne demek istediğimi anlarsınız.
    Bir “power user” olarak bazen engel gibi geliyor, ama herkesi hesaba katmak gerektiğini anlıyorum.
  • Bu yorumu görünce Every Page Is Page One hoşuna gidebilir diye düşündüm. Ana fikir şu: İnsanlar bir dokümantasyon sitesinin herhangi bir sayfasından içeri girebilir; bu yüzden her sayfa hızlıca bağlam vermeli ve kullanıcının doğru yolda olup olmadığını kolayca değerlendirmesini sağlamalı.
    Kitabın adı da buradan geliyor. Sitedeki herhangi bir sayfa, kullanıcı için ilk sayfa olabilir.
  • Keşke bu yaklaşım daha fazla teknik dokümantasyonda olsa. Bir şeyin neden belirli bir şekilde yapıldığını sürekli merak eden biriyim; bu yüzden yan konulara sapıp yavaşlayabiliyorum.

• LLM kullanma biçimimle iyi örtüşüyor. Her zaman seçenekleri istiyorum, sonra içlerinden hangisinin en mantıklı olduğuna kendim karar veriyorum.
  Özünde onu, karar verme sürecinin her anında olası seçenekleri eksik ama faydalı biçimde dışarı döken, tuhaf ve sihirli bir belge gibi kullanıyorum.

  • Leonardo gibi ünlü sanatçıların yanında çalışan çırakları düşünmek yeterli. Usta ana hatları ve eskizleri çizer, öğrenciler de gözetim altında boşlukları doldurur. Bazen usta, öğrencilerin fikirlerini de çalar.
  • Bu yönteme bir örnek verebilir misin?

• Gerçekten iyi. Kısa, öz ve içgörülü. Ben büyük resmi görmeye yakın bir düşünce yapısındayım; bu yüzden bir şeyin yalnızca nasıl yapıldığı değil, neden öyle olduğu ve daha geniş bağlamla nasıl bağlantılandığı da önemli.
  Geliştiricilere Jira story’leri ve görevlerdeki Description alanını aktif kullanmalarını; neden bu işi yaptığımızı ve büyük resme nasıl bağlandığını özetlemelerini öneriyorum. Bazıları bundan hoşlanmıyor gibi, ama bazıları epey seviyor.
  Ben projenin büyük resmini sunduğum için memnunum; geliştiriciler de o büyük resmi anlayarak daha bağımsız çalışabildikleri için tatmin oluyor.

• Dokümantasyonun insanların iyi kararlar almasına yardımcı olup olmadığını ölçmek, bir görevi başarıyla tamamlamalarına yardımcı olup olmadığını ölçmekten çok daha zor görünüyor.
  Görev odaklı/prosedürel dokümantasyona optimize edilmesinin nedeni, şirketin dokümantasyon ekibinden değerini kanıtlamasını istemesi, bu tür dokümantasyona talep olması ve kısa süre içinde ölçüp raporlayacak çok sayıda yol bulunması.
  Ama “Bu doküman kümesi birinin doğru şeyi doğru şekilde oluşturmasına yardımcı oldu mu?” sorusu, kuruluşların kendi ürünleri için bile yanıtlamakta zorlandığı türden; bunu dokümantasyon etkisine soyutlayınca çok bulanık hale geliyor.
  Karar vermeye yardımcı dokümanlar yazılamaz demiyorum; bunu yaptığınızı sayılarla kanıtlamanın çok zor olduğunu söylüyorum. Çeşitli doküman kümelerinin karar vermesi gereken kullanıcıları ne kadar iyi desteklediğini sıralayıp gerekçelendirebilirim, ama bunu şirketin istediği şekilde nasıl nicelleştireceğimi pek bilmiyorum.
  Karar vermeyi desteklemek üzere tasarlanan bir doküman kümesinin yapısının, görevleri destekleyen dokümantasyondan nasıl farklı olacağını da merak ediyorum. Büyük kategoriler yine kavramlar, referanslar ve rehberler olurdu; ama muhtemelen çok daha fazla kavramsal doküman ve kavramları bağlama oturtmak için daha fazla alan olurdu. Konular arası bağımlılıkların ve çapraz referansların da artmasını beklerim.

  • İlk düşüncenin “Bunu yazdığım dokümantasyonu iyileştirmek için nasıl kullanırım?” değil de “Bunun yazdığım dokümantasyonu iyileştirdiğini nasıl kanıtlarım?” olması ilginç. Epey sıkı bir ortamda çalışıyor gibisin.
  • Kişisel proje gibi, kullanıcılar için en iyisi olduğunu düşündüğün şeyi özgürce yapabildiğin yerlerde karar desteğini dokümantasyon stratejisinin temeli yapma olasılığı yüksek.
    İşini özenle yapmak açısından, kendi projemde “karar desteği”nin en iyi yol olduğunu hissedersem, bu stratejiyi işteki dokümantasyona da taşıma yükümlülüğüm varmış gibi geliyor.
    Neyse ki kısa görüşlü yöneticiler boğazımıza çökmüş değil; ama iş yerinde ikna etmem gerekse şöyle yapardım. Önce stratejinin mantığını açıklarım. Karar desteği mantıklı ve ikna edici. Görev dokümanları yine yazılır, ama görevler karar desteğinin yalnızca bir alt kümesidir.
    Ardından destek talepleri, sohbet odası tartışmaları vb. içinden karar desteği eksikliğinin sorun olduğu örnekleri uzun uzun sunarım. Entelektüel dürüstlük adına dokümantasyonla ilgili tüm destek taleplerinin listesini ve bunların içindeki karar desteğiyle ilgili alt kümeyi birlikte gösteririm. Oran göz ardı edilemeyecek düzeydeyse, örneğin %25 ise “karar desteği”ne daha derin bakmak gerekir.
    Son olarak paydaşların kendi işlerinde yaşadığı örnekler verilebilir. “CMS’i neyle değiştireceğimize karar vermenin gerçekten zor olduğunu hatırlıyor musunuz?” gibi.

• Genelde benim sezgisel yaklaşım dediğim şey bu.
  İşlerde bulanık mantık benzeri bir yaklaşıma ihtiyaç olduğunu hissediyorum. Ancak en iyi, mühendisin belli bir deneyimi olduğunda çalışıyor.
  Deneyim eksikse, kişi yetenekli ve zeki olsa bile çok daha yönlendirici olmak gerekiyor.

  • Thinking in Bets, yazılım mühendisliğine yaklaşımım açısından en faydalı kitaplardan biriydi. Kodla ilgili bir kitap değil; sınırlı bilgi ortamlarında etkili karar vermeyle ilgili bir kitap.
  • İşe bulanık mantık tarzında yaklaşmak ne demek tam anlayamadım. Biraz daha açabilir misin?

• Ekip bağlamında karar vermeye iyi bir yaklaşımı Rich Hickey burada anlatıyor: https://www.youtube.com/watch?v=c5QF2HjHLSE
  Konuşmanın başlığı “Design in Practice”, ama aslında konu karar verme.

• “İş dediğin, bir karardan bir sonraki karara geçmek için yapılması gereken her şeydir.” — Venkatesh Rao, Tempo

• Benzer bir şeyi savunageldim. Araçları yalnızca üst düzeyde anlatmakla yetinmeyin; özellikle insanlar sık sık pazarlama moduna giriyor. Bunun yerine, aracın hangi sorunu çözmek üzere tasarlandığını ve bu süreçte hangi ödünlerin verildiğini anlatmak gerekir.
  Böylece aracı, mevcut seçenekleri ve modları bağlama oturtmak çok daha kolaylaşır; size uygun olup olmadığına da hızla karar verebilirsiniz.

• Bu tavsiye bana biraz kafa karıştırıcı geliyor. Kimin kararı? Aracı geliştirenin kararı mı, kullanıcının kararı mı?
  Genel olarak aşırı basitleştirme gibi görünüyor. Önce yazdığınız belgenin öğrenme amaçlı mı, hedef odaklı mı, anlama amaçlı mı yoksa bilgilendirici mi olduğunu kavramak daha faydalı olur [1]
  Örneğin bir fonksiyonun API’sine bakarken üzerinize “karar” bilgisi yağarsa bu can sıkıcı olabilir.
  1 - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...

  • Dokümantasyon her zaman kullanıcı ihtiyaçlarını ele almalıdır. Bu ortadan kalkmaz. Sözünü ettiğiniz dokümantasyonun dört kadranı olan Diataxis için de aynı şey geçerli.
    Bence bu yazının karşılık bulmasının nedeni, iyi bilinen iki stratejinin kör noktasını ortaya koyması. Herkes kullanıcı odaklı dokümantasyon oluşturmaya çalışıyor ve birçok ekip Diataxis’i izliyor, ama yine de insanlar dokümantasyonla işlerini bitirmekte zorlanıyor.
    “Dokümantasyon kararları desteklemelidir” temel bakış açısından başlamak, dokümantasyonu daha kullanışlı hâle getirmenin bir yolu olabilir.

• İnsanların benim sistemimi nasıl kullanıp karar aldığını bilmek önemli. Böyle bir bilginin sistemi bakımını yapmak, genişletmek ya da yeniden oluşturmak için şart olduğunu düşünüyorum.
  Ama yazı daha yüksek bir sorumluluk öneriyor: kullanıcının karar alma sürecini belgelemek; bağlamı, seçenekleri ve kararın sonuçlarını anlatmak gerektiğini söylüyor.
  Böyle bir sorumluluğu olan bir “karar destek sistemi” üzerinde çalıştım; çok hızlı biçimde karmaşıklaştı. İnsanlar sonuçlar %100 kesin olarak bilinse bile o sonuçlar üzerine tartışmayı seviyor. Belirsizlik içeren otomatik e-postalardan da hoşlanmıyorlar; gerçekte çok daha fazla seçenek varken dokümantasyonun ikili bir seçim dayatmasından da hoşlanmıyorlar.
  Bu yazının ötesinde, kitabın kontrol kavramını ele almasını isterdim. Bir davranışı belgelemek için, dokümanın otoritesini koruyabilmesi adına o davranış üzerinde belli ölçüde garanti ya da yaptırım olması gerekir. Kişisel olarak otorite ve kontrol eksikliğinin https://www.plainlanguage.gov gibi yazım girişimlerinin yaygın ve büyük kör noktalarından biri olduğunu düşünüyorum.

  • r/technicalwriting’de bu yazı hakkında yazdıklarımı yeniden alıntılarsam, Baker’ın fikrindeki gerçekten önemli nokta, teknik dokümantasyon eğitiminin öğretisinin mutlak biçimde görev odaklılığa ayarlanmış olması.
    Profesyonel teknik yazarları araştırırsanız, büyük çoğunluğun dokümantasyonun başlıca hedefinin, hatta belki de ASIL hedefinin “kullanıcının bir görevi başarmasına yardımcı olmak” olduğuna inandığını görürsünüz.
    Baker’ın kısa alıntısı, Latince anlamıyla “köklere dönmek” bakımından epey radikal; çünkü temel varsayımlarımızdan birinin ciddi biçimde yetersiz olduğunu öne sürüyor.
    Kişisel olarak Baker’ın fikrini ilginç bulmamın nedeni, teknik dokümantasyondan bugün beklenen standartların çok üzerinde bir standart koyması. Pek çok doküman, görev belgelendiğinde “görev tamamlandı” varsayımını yapıyor; ama Baker yalnızca bunun yeterli olmadığını söylüyor gibi.
    Görevlerin elbette hâlâ belgelenmesi gerekir; ancak görevler, bir kararı oluşturan bilginin alt kümesidir.
    Baker’ın kitabının burada söz ettiğiniz anlamda kontrolü tartışıp tartışmadığını hatırlamıyorum. Benim için yeni bir fikirdi, teşekkürler.
    Aklıma gelen somut bir kontrol örneği şu: Dokümantasyonumun önemli bir kısmı başka açık kaynak projelerinin sayfalarına dayanıyorsa ve o dış sayfaların kalitesi düşükse, o dokümantasyonu iyileştirmek de muhtemelen benim sorumluluğum olmalıdır. Birçok kişi kendi sitesi dışındaki dokümanları kendi sorumluluğu dışında görebilir; ama gerçekten kararları desteklemeyi amaçlıyorsanız, dokümanı kimin barındırdığı önemli değildir.
    İyi bir açık kaynak vatandaşı olma tavrından öğrenilecek çok şey olabilir.