Düzenleme Yaparken Düşündüklerim (2019)
(evaparish.com)- Düzenleme, cümleleri cilalamadan önce metnin gerçekten ne söylemek istediğini ve okurunu doğrulama işidir; aynı temel ilkeler e-postalara, belgelere, blog yazılarına ve romanlara da uygulanabilir
- Metnin başında ve sonunda ana fikri yeniden vurgulamak, “this/that” gibi işaret sözcükleri yerine isim kullanmak, okurun bağlamı kaçırmamasını sağlayarak netliği artırır
- Gereksiz sözcükleri azaltmak, yönergeleri emir kipine çevirmek, uzun cümleleri ve “of/for” yapılarını parçalamak anlamın daha hızlı iletilmesini sağlar
- Edilgen çatı, zarflar, jargon ve klişeler eylemi yapanı, kesin anlamı ve okur kapsamını belirsizleştirebileceğinden, bunları daha somut fiiller ve açıklamalarla değiştirmek daha iyidir
- İyi düzenleme, kuralları körü körüne izlemek değil; iletilmek istenen mesaja uygun dil seçimlerinin bilincinde olmak ve gereksiz ifadeleri kaldırmaktır
Metnin Gerçekte Ne Söylediğini Önce Belirlemek
- Cümle düzeyinde düzenlemeye geçmeden önce, metnin amaçladığı şeyi gerçekten söyleyip söylemediğini kontrol etmek gerekir
- Her metin için kişisel bir preamble (ön açıklama) yazmak, düzenleme ölçütü oluşturur
- Temel sorular “Ana nokta nedir?” ve “Kim için yazılıyor?” sorularıdır
- Bu bilgileri belgenin en üstüne yazıp, yazma ve düzenleme sırasında gerçek içerikle karşılaştırın
- Bir blog yazısının ana noktasını bir iki cümleyle özetleyemiyorsanız, tutarlı bir yazı yazmak zordur
- Writers Studio yaratıcı yazarlık derslerinde her ödev için amaçlanan anlatıcıyı, tonu ve atmosferi içeren bir preamble yazılır; değerlendirme ise beğeniden çok tekniklere ve niyetin gerçekleşip gerçekleşmediğine odaklanır
Tekrar, Okuru Metinde Tutan Bir Araçtır
- Ana fikir yeterince açık görünse bile, metnin başında ve sonunda tekrar söylendiğinde okur noktayı daha iyi takip edebilir
- Belge öğreticilerinde genellikle ne yapılacağını tanıtmak, adımları vermek ve ardından doğru yapılıp yapılmadığını doğrulamak iyi bir yapıdır
- Blog yazıları için de ele alınacak konuyu tanıtmak, gövdede geliştirmek ve sonda kısa bir özet vermek uygundur
- Dil düzeyinde de tekrar gerekir
- İşaret zamirleri olan “this” ve “that” ile yetinmeyin; neyi gösterdiklerini belirten bir isim ekleyin
- “To solve this” yerine “To solve this shortage” daha nettir
- “That will take you to the home screen” yerine “Successfully authenticating will take you to the home screen” daha belirgindir
- Yazara tekrar gibi gelse de, okur için metni takip etmeyi kolaylaştıran bir netleştirme işlevi görür
Sadeleştirme: Anlamı Olmayan Sözcükleri Çıkarmak
- Düzenlemede en önemli iş, anlama katkı sağlamayan sözcükleri kaldırmaktır
- “You will need to run this script” cümlesi “Run this script” olarak kısaltılabilir
- “You can aid in readability by making sure…” cümlesi “Make sure…” olarak kısaltılabilir
- Özel bir neden yoksa konuya mümkün olduğunca hızlı ulaşmak, anlamı aşırı sözcüklerin ve süslü cümle yapılarının altına gömmemek gerekir
-
Yönergeleri emir kipine çevirmek
- Yönergelerde “You should X”, “You can X” ifadelerini fiilin emir kipine çevirmek genellikle daha özlüdür
- “You should save the file to your home directory”, “Save the file to your home directory” olur
- Bu değişiklik sözcük sayısını azaltır ve okuru doğrudan eyleme yönlendirir
-
“of” ve “for” yapılarını azaltmak
- “of” veya “for” ile uzayan yapılar, bilgiyi ismin önüne yerleştirecek şekilde yeniden yazıldığında daha verimli olur
- “The manager of the team responsible for marketing”, “The marketing team’s manager” olur
- Yeniden düzenlenen cümle, okurun her yan cümlede anlamı düzeltmek zorunda kalmadan anlamı daha hızlı kavramasını sağlar
-
Uzun cümleleri bölmek ve virgül
- Uzun cümleleri birkaç kısa cümleye ayırmak daha iyidir
- Acme projesi örneğinde tek bir cümlede milestone, sunucu ortamı, derleme süresi iyileştirmesi ve XYZ planı karşılaştırması vardı; düzeltilmiş sürüm bunları üç cümleye ayırdı
- Düzeltilmiş sürüm, non-staging sunucularının Foobaz ortamında çalıştığını, derlemenin 10 dakikanın altına düştüğünü ve XYZ planında bunun daha önce 1 saatten uzun sürdüğünü ayrı ayrı aktarır
- Uygun yerlere virgül eklemek, okurun ilk kısmı işleyip ardından kalanını okumasını sağlar
- “If you’re looking for me, I’ll be in my office”
- “Due to the fog, our flight was delayed”
- Cümlenin başında bağımlı bir yan cümle geldiğinde virgül gerekir; bu virgül okumaya yardımcı olan bir işleme noktası olur
Eylemi Yapanı ve Anlamı Bulanıklaştıran İfadeleri Azaltmak
-
Edilgen çatıyı kaldırmak
- Edilgen çatı, eylemi kimin veya neyin gerçekleştirdiğini gizler
- Edilgen yapıyı etken çatıya çevirmek, okurun eylemi doğru kişi veya nesneyle ilişkilendirmesini sağlar ve cümleyi daha net hale getirir
- “The fire alarm was pulled and the building was evacuated”, “The fire marshal pulled the alarm and the employees evacuated the building” gibi eylemi yapanları görünür kılar
- “Millions of dollars were embezzled from the company”, “Two executives embezzled millions of dollars from the company” gibi kimin yaptığını açıklar
- Sistem açıklamasında “An alert is triggered and the job is started” yazarsanız, hangi servisin uyarıyı tetiklediği ve hangi bileşenin işi çalıştırdığı ortaya çıkmaz
- Teknik dokümantasyonda eylemin öznesini belirtmemek kesinliği azaltır
-
Zarflar yerine somut fiiller ve betimlemeler kullanmak
- Zarflar neredeyse her zaman daha somut bir fiil veya açıklamayla değiştirilebilir
- “He laughed loudly” cümlesindeki “loudly”, okurun gülüşün tam sesini veya hissini tahmin etmesine neden olur
- Gerçek niyet “restorandaki herkesin döneceği kadar yüksek sesle güldü” ise, bu durumu doğrudan betimlemek daha somuttur
- “Basically”, “Essentially” gibi zarflar çoğu zaman hedge olarak kullanılır; bunları kaldırıp söylemek istediğinizi doğrudan söylemek daha iyidir
Okurun Bilgisini ve Tonu Varsaymamak
-
Kısaltmaları ve kavramları açıklamak
- İyi bildiğiniz bir konuda yazarken okurun bilmediği arka planı unutmak kolaydır
- Kısaltmalar ve baş harflerden oluşan terimler ilk geçtiğinde açılmalı, parantez içinde kısaltması verilmeli ve sonrasında yalnızca kısaltma kullanılmalıdır
- “TTFB” ilk kullanımda “time to first byte (TTFB)” olarak yazılır
- Kavram ilk kez geçtiğinde kısa bir açıklama eklemek okurun takip etmesini kolaylaştırır
- TTFB, kullanıcının HTTP isteği gönderdiği andan tarayıcının ilk baytı yüklemesine kadar geçen süreyi ölçer
- Web sitesi yanıt verebilirliğini gösteren bir metrik olarak kullanılır
- Gerekirse time to first byte (TTFB) metric gibi ek öğrenme bağlantıları sağlanabilir
-
Ton tutarlılığı
- Metnin tonu ister konuşma dili ister resmî olsun, tek bir çizgide belirlenmeli ve tutarlı biçimde korunmalıdır
- Bir cümle çok konuşma diliyle başlayıp akademik bir ifadeye dönerse, okurun kafasını karıştırabilir veya dikkatini söylenmek istenen şeyden uzaklaştırabilir
- Örnek cümle, “yeni framework için başta heyecanlandık ama istediğimiz metrikleri yakalayamadık” gibi tutarlı bir tona dönüştürülebilir
Jargonu, Klişeleri ve Görsel Yapıyı İyileştirmek
-
Jargon ve klişelerden kaçınmak
- İş dünyası jargonunda “deep dive”, “low-hanging fruit” gibi ifadeler vardır; başka metinlerde de beyzbol metaforları gibi klişeler sık kullanılır
- Jargon, okurun bu ifadeyi kullanan iç gruba dahil olduğunu varsayar
- Ana dili İngilizce olmayan veya beyzbol kültürüne aşina olmayan okurlar için jargon ve klişeler metni takip etmeyi zorlaştırabilir
- “tl;dr, if you can hack something together by EOD…” ifadesi kısaltmalar ve teknik argo içerir, ayrıca bir istek gibi duyulmaz
- “Can you deliver a prototype by the end of today?” gerekli çıktıyı ve son tarihi doğrudan soran net bir istek haline gelir
-
Boşluk ve biçimlendirmeden yararlanmak
- Boşluk teknik dokümantasyonda önemlidir; blog yazılarında ve e-postalarda da etkilidir
- Uzun paragraflar özellikle bilgisayar ekranında okunması zordur ve okurun odağını kaybetmesine yol açabilir
- Sayfayı görsel olarak bölmek ana noktaları bulmayı kolaylaştırır
- Uzun paragrafları birkaç kısa paragrafa bölün
- Yararlı alt başlıklarla yapı kurun ve okurun ilgilendiği bölüme atlamasını sağlayın
- İlgili öğeleri liste olarak yazın
- Referans dokümanları gibi çok bilgi aktarırken tablolar listelerden daha iyi olabilir
- Göz gezdiren okurların ana noktaları yakalayabilmesi için kalın yazımı kullanın
Düzenleme Felsefesi
- Düzenleme felsefesi iki noktaya indirgenebilir
- Zarflara, jargona, klişelere ve hedge ifadelerine yaslanmadan tam olarak ne demek istediğinizi söyleyin
- Gereksiz tüm sözcükleri kaldırın
- Bu iki ilke, kendi yazınızı düzeltmek ve başkalarının yazılarını değerlendirmek için bir çerçeve olur
- Pratikle kendi stiliniz ve tercihlerinizi geliştirirsiniz; nedenini bildiğiniz sürece bazı önerilerden sapmanızda sakınca yoktur
- Düzenlemenin amacı kuralları eleştirmeden izlemek değil, dil kullanımının bilincinde olmak ve iletmek istediğiniz mesaja uygun seçimler yapmaktır
1 yorum
Hacker News yorumları
Bu yazının yazarı benim. Bu kadar çok kişiye dokunmuş olmasına sevindim ve onur duydum. Yazıyı yazdıktan sonra merakımın peşinden gidip bizzat yazılım mühendisi oldum; birkaç yıl çalışınca yazmanın büyük yer tuttuğu bir rolü özlediğimi fark ettim Çok iyi bir teknik yazar, developer advocate ya da iletişim uzmanlığı ile teknik yetkinliği birleştiren bir rol arıyorsanız bana haber verin. Web sitesi formu (https://evaparish.com/contact) veya LinkedIn üzerinden ulaşabilirsiniz
Teknik belgeleri okurken beni en çok rahatsız eden şeylerden biri, okuyucuya henüz tanıtılmamış kısaltmaların geçmesi. Proje belgelerinin çeşitli yerlerinde bu tekrar tekrar oluyor; birkaç yıl içinde sorumlular değişince belirli bir kısaltmanın neyin kısaltması olduğunu kimsenin bilmediği noktaya bile geliniyor Gerçekten de bir ekibin ABC adlı bir servisi geliştirip bakımını yaptığı, ama ekipte kimsenin ABC’nin neyin kısaltması olduğunu bilmediği tuhaf durumları birkaç kez gördüm. Böyle durumlarda yeni bir ad seçip ilgili tüm belgeleri güncelleme işinden kaçınmak için ABC’yi özel isim gibi ele alıp geçiyorlar Uydurma örnek: CDIS için erişim token’ı almak üzere ’nın DMC’sine gidin, sol kenar çubuğundaki "CDIS" öğesine tıklayın ve token’ı kopyalamak için "Generate Access Token"a basın Bunun yerine şöyle okumak isterdim: Customer Data Indexing Service (CDIS) için erişim token’ı almak üzere ’nın Data Management Console’una (DMC) gidin, sol kenar çubuğundaki "CDIS" öğesine tıklayın ve token’ı kopyalamak için "Generate Access Token"a basın