Belgelerin Kabulü
Önceki Ne NASIL yapılır? Sonraki
Belgelerin Kabulü
Yayınlanmak üzere gönderilen ya da başka kaynaklardan toplanan belgeler 3. şahıslara kopyalama ve dağıtma izni verilmesi önkoşuluyla Kitaplığımızın altındaki "Belge Arşivi"'nde bir öndeğerlendirmeden sonra yayınlanabilir.
Belge Arşivi'ndeki belgeler burada belirtilen kurallar dahilinde onay kurulumuz tarafından değerlendirmeye alınır. Onay kurulumuzca alınan tavsiye kararlarına uygun olarak belge düzeltildiğinde işbu belge kitaplığımızın uygun bir kitabına dahil edilir. Bu işlem genellikle belge arşive girmeden yazar ile iletişim aşamasında gerçekleşmekte ve belge doğrudan kitaplığımıza eklenmektedir.
Yazarı bulunamayan ya da tavsiye kararına uygun güncellemesi yapılmayan tüm belgeler ile güncelliğini yitirmiş belgeler Belge Arşivinde kalmaya devam eder.
Bu bölümün devamında bir belgede aranılacak özellikler anlatılmıştır. Belge gönderen bu bölümdeki kuralları okumuş ve kabul etmiş sayılır.
Genel Kurallar
Bu bölümde belgeleri hazırlarken dikkat edilecek bazı genel kurallardan söz edilecektir.
  1. Kitaplık kapsamında hazırlanacak tüm belgeler ister bir makale ister bir kitap olsun, Docbook-xml ile yazılmalıdır. Docbook-xml belgelerin nasıl hazırlanacağını Linux Belgeleri NASIL'dan öğrenebilirsiniz. Çeviri belgeler ise başka bir biçimde hazırlanmış olsalar bile docbook-xml'e dönüştürüldükten sonra çevrilmelidir.
  2. Belgelerdeki book, part, chapter, sect1, article ya da ilk section elemanlarının ID parametrelerini boş bırakmayın. Bu ID'ler HTML dosyalarının ismi olarak kullanıldığından önemlidir.
    Kitaplıkta kullanılacak bir belgenin tepe elemanının ID parametresini alt elemanlarında önek olarak kullanırsanız başkalarını ID seçimi konusunda daha serbest bırakmış olursunuz. Dosya isimlerinin uzun olmasından çekinmeyin. ID'lerin eşsiz olması daha önemlidir.
  3. Tüm ID parametrelerinin değerlerini küçük harflerle yazın.
  4. Belge içi bağlarda kullanacağınız ID değerlerini daima belgenin tepe elemanının ID değerini önek olarak kullanarak oluşturun.
    Örneğin, Turkish-HOWTO.xml dosyasındaki tepe elemanı article'dır ve ID parametresi
    <article id="turkish-howto">
    olarak verilmiştir. Belge içinde Türkçe F klavye dosyasına bağ verirken
    <link linkend="turkish-howto_trf">trf.kmap.gz</link>
    kullanılmıştır. Burada dikkat ederseniz linkend parametresinde kullanılan ID parametresi article elemanının ID değerinin sonuna trf eki getirilerek oluşturulmuştur. Bu bağın hedefindeki elemana bakarsak:
    <sect1 id="turkish-howto_trf">
    olduğunu görürüz.
  5. programlisting, screen, literallayout elemanları ile sarmalanmış metin parçaları sabit genişlikli yazı tipi ile boşlukları korunarak gösterilirler. Bu metinler XML dosya içinde yazılırken satır başlangıcından ne kadar uzakta ise gösterilirken kendi bölgesinin sol kenarından o kadar içerde gösterilirler. Dosyayı biçimli yazmak isterseniz buna özellikle dikkat etmelisiniz. Bu alanlardaki metinleri düzenlerken kesinlikle sekme (tab) tuşunu kullanmayın Sekme karakterinin içerdiği boşluk sayısı kişisel seçimlere bağlı olarak değişiklik gösterir ve bu belge üzerinde bir başkası çalıştığında herşey farklı görünebilir. Bu bakımdan sadece boşluk karakterini kullanmalısınız.
  6. Belgeyi yazarken kullandığınız karakter kodlamasını XML dosyasının başlığında belirtin:
    <?xml version="1.0" encoding="UTF-8"?>
    Sistemlerini LANG="tr_TR" çevre değişkeni ile belirtilen kodlama ile kullananlar için bu başlık:
    <?xml version="1.0" encoding="ISO-8859-9"?>
    LANG="tr_TR.UTF-8" çevre değişkeni ile belirtilen kodlama ile kullananlar için:
    <?xml version="1.0" encoding="UTF-8"?>
    olacaktır. Bu değer, XML dosyasının XSL dönüşümü yapılırken, yani HTML biçime dönüştürülürken dosya içindeki karakterlerin hangi dil kodlamasına göre değerlendirilmesi gerektiğini belirtmek için kullanılır. Oluşturulan HTML dosyasının dil kodlaması için bu değer kullanılmaz. O dönüşüm sırasında belirlenmektedir. Siz XML dosyayı hangi dil kodlamasıyla yazarsanız yazın HTML dosyalar ISO-8859-9 kodlama ile oluşturulur.
  7. Satırsonu karakterlerinin UNIX türünde olmasına dikkat edin. Yani satırsonu karakteri sadece LF karakterinden oluşmalıdır, Windows'daki CR+LF ve Mac'deki CR karakterlerinden değil. Bu bakımdan dosya üzerinde Linux dışında bir ortamda çalışıyorsanız, dosyanın UNIX türünde oluştuğundan emin olun.
ID'ler ile ilgili kurallardan, belge çok büyük ve değiştirilmesi büyük emek harcanmasını gerektiriyorsa vazgeçilebilir. Bu tür belgeler çoğu zaman kitap formundadırlar. Bunlar kitaplık kapsamına alınmaz ve kitaplıktan ayrı yayınlanır. Buna en iyi örnek olarak, yaklaşık 15MB'lık boyutuyla PHP-Manual gösterilebilir. Bu tür belgelerin sözlükten ve kitaplık kapsamındaki belgelerden ancak sabit bağlarla yaralanabileceği, iç çapraz bağları kullanamayacağı açıktır.
Çeviri Yaparken Nelere Dikkat Etmeli?
Orjinaline yakınlık
Çevirilerin mümkün olduğu kadar orjinaline yakın olması beklenmektedir. Çevirilerde hedef, çeviriyi okuyan kişinin orjinaline ihtiyaç duymamasıdır. Dolayısıyla bir belgenin çeviri olabilmesi için kısaltılmadan, cümlenin bazı bölümleri atlanmadan yani serbest çeviri olarak değil, tamamen çevrilmesi gerekir.
Bilgisayar dünyası hızlı gelişen bir dünya olduğu için zaman zaman çeviri yapılan bir belgede orjinalinde olmayan güncellemeler veya bazı ek açıklamalar yapma gereği çıkabilir. Bu tarz, çevirmen katkıları, ayrıca <footnote> elemanları ile sarmalanarak [Ç.N.: bla bla] şeklinde dip notlarda gösterilmelidir. Docbook yapısı bu dipnotları kendiliğinden oluşturmakta ve dipnotlara gidip geri dönmek bir sorun teşkil etmemektedir.
Üslûp
Çeviri belgelerde orjinalinin üslubu esastır. Dil yapısının farklılığının gerektirdikleri haricinde, orjinalinin yazarı ne yazmış ise, bu çevrilmelidir. Örneğin 1. tekil şahıs ile samimi ve araya şakalar serpiştirerek yazılmış bir belge, üçüncü şahısta, bu şakalar olmaksızın, ciddi bir üslupla çevrilemez.
Buna rağmen, çevirinin Türkçesi akıcı olmalı ve çeviri kokmamalıdır. Örneğin çeşitli deyimler birebir çevrilmemeli, aynı manayı veren Türkçe deyimlerle değiştirilmelidir. Çevirmenin o an aklına gelmeyen Türkçe sözcüklerin yerine İngilizce orjinallerini kullanıvermesi, (örnek: Şimdi "daemon"larınızı "restart" edin), Türkçe'de olmayan cümle yapılarını kullanması (örnek: o kullanıcılar ki, her gün makinayı yeniden başlatırlar, onlara yapılacak birşey yoktur) gibi dublaj Türkçesinden sakınmak gereklidir.
Dil
Çeviri belgeler yabancı dil bilmeyen veya az bilen Türkler tarafından okunacaktır.  Dolayısıyla belgenin dili Türkçe olmalıdır.
Terimler
Genelde karşılaşılan sorun, bazı terimlerin Türkçe'sinin henüz olmaması veya ilgili çevirmen tarafından terimin Türkçe karşılığının bilinmemesidir.  Bu noktada hemen kolaycılığa kaçmak ve terimin orjinalini olduğu gibi kullanmak (daemon'ları restart edin) belgenin Türkçe'den başka bir dil bilmeyen ana hedef kitlesi tarafından okunduğu zaman anlaşılamamasına, dolayısıyla hedefine ulaşamamasına yol açacaktır.
Bu noktada çevirmen, kendi sözcük dağarcığını zenginleştirmek ve gerek sözlük kullanmak, gerek listesinden yardım istemek sureti ile ilgili terimin Türkçe'sini bulmak ve kullanmakla mükelleftir.  Gerçekten Türkçe'de ilk defa kullanılacak olan bir terim ise, uygun Türkçe karşılığının ne olması gerektiği tartışılmalı ve ilgili sözlüklere ilave edilmelidir.  Çeviri belge üretmenin ikincil hedefi de bir bilgisayar dili olarak Türkçe'nin zenginleşmesi ve kullanılmasını sağlamaktır.
Kimi zaman dilimize ilk olarak orjinali ile kısıtlı miktarda geçmiş, fakat zaman içerisinde Türkçe'si de türetilmiş olan terimlerle karşılaşılabilir. (Örnek: proxy/vekil, kernel/çekirdek vb) Burada, eğer çevirmen Türkçe'sinin yaygın olmadığından kuşku duyar ise, terimi ilk kullandığı zaman orjinalini yanında vermeyi tercih edebilir (örneğin:  vekil sunucular [İng.: proxy] faydalı şeylerdir). Çevirmen, belgenin kalan kısmında Türkçe'sini kullanarak terimin yaygınlaşmasını sağlamakla mükelleftir. Terim ilk kullanıldığı zaman yanında orjinalini bir sefere mahsus göstermek, bir kural değil, bir istisnadır ve yalnızca gerçekten İngilizce bilmeyen kullanıcılar tarafından da orjinal terimin bilinme ihtimali olan durumlarda başvurulacak bir yöntemdir.
Yabancı kökenli sözcükler kullanmak
Her ne kadar bilgisayar terimleri konusunda, uzmanlık sahası gereği olarak, terim oluşturmak ve kullanmak yolu ile Türke'ye bir katkı sağlamak çevirmenin ve belge hazırlayıcılarının ikincil hedefleri arasında olsa da, genel anlamda dil değişiklikleri bu grubun uzmanlık sahasının dışına çıkmaktadır.
Dolayısıyla bir belgede terimlerle ilgili Türkçe kullanımı konusunda değerlendirmeler yaparken, çevirmenin çeviri yerine tercüme (veya tam tersi) gibi her ikisi de günlük yaşayan Türkçe'de bulunan sözcükler arasında yaptığı tercihlere karışılmaz. Fakat, bu noktada, özellikle son yıllarda yaygınlaşan, herhangi bir yabancı sözcüğün karşılığı olup olmadığı düşünülmeksizin birebir ithal edivermek kolaycılığına düşülmemelidir. Örneğin çeviri veya tercüme kullanılabilir, fakat tradüksiyon kullanılmamalıdır. Çeviri veya tercüme örneğine tekrar geri dönersek, gönlümüz çeviri'den yanadır.
Mümkün olduğu kadar öz Türkçe kullanımı esastır, fakat çevirmenin bunu bir düstur olarak kabul etmesi beklenmekte, çeviri onay mekanizmasının bu noktada elde TDK sözlüğü, teker teker her sözcük üzerinde inceleme yapması beklenmemektedir.
Bu noktada da çizgi, yine dublaj Türkçe'sinden geçmektedir.  Bir yakınımın, altyazılı bir filmde Cibuti'yi "Djibouti" olarak altyazılarda gördüğü zaman dediği gibi  "Allah bilir altyazıyı hazırlayananın dedesi orada şehit olmuştu..." tarzından serzenişlere yer bırakmayacak şekilde dil kullanımı yapılmalıdır. Yer isimleri Türkçe karşılıkları ile çevrilmelidir (örneğin Aleppo, Halep'tir. Morocco, "Morako" olarak değil, Fas olarak çevrilir gibi).
Hedefimiz, akıcı ve anlaşılır bir Türkçe kullanımını teşvik etmektir.
Onay
Yukarıdaki özelliklere uygun olan bir çeviri belge onaylanır. Çevirilerde esas, orjinalini, akıcı ve anlaşılır bir Türkçe ile yansıtmasıdır.
Yeni Belge Hazırlarken Nelere Dikkat Etmeli?
İçerik
Hedef Kitle
Belgelerde esas, çeşitli seviyelerdeki bilgisayar kullanıcılarına faydalı olmasıdır. Bu sebeple, belge yazarı belgenin kime, ne fayda sağlayacağına dair bilgiyi belgenin başında vermelidir.  Bu bilgi, belgenin genel değerlendirmesinde büyük önem kazanacaktır.
Örneğin eğer başlangıç kullanıcısına yönelik bir belge ise, bu kullanıcının  çekirdeğe bir modül yazabileceğini varsaymak, belgenin bir işe yaramamasına yol açacaktır.
Tarih, Bağlam
Bilgisayar dünyası hızla gelişmekte ve dünün problemleri kısa zamanda problem olmaktan çıkmaktadır. Dolayısıyla yazılacak bütün belgelerde belgenin tarihi, kullanılan protokollerin sürümleri, işletim sistemi sürümü, vb gibi problem ve imkanların varlığını bir zaman çizgisine oturtmaya yarayacak bilgiler açık olmalıdır.
Örneğin Linux'un dinamik filtreleme yapamayacağından bahseden bir güvenlik duvarı belgesi, eğer bunu "XX tarihinde, ipchains sürüm YYY ile dinamik filtreleme yapılamaz" şeklinde belirtirse, dinamik filtrelemenin her dağıtımda öntanımlı olarak var olduğu 2002 yılında bunu okuyan bir kullanıcı bu zaman aşımına uğramış bilgi yüzünden yanlış yönlendirilmeyecektir.
Örnekleme
Mümkün olduğu kadar belgeler her dağıtım, her sürümde üzerinde uygulanabilecek genel kavram ve bilgiler içermelidir. Fakat örnekler, mümkün olduğunca spesifik uygulamalar üzerinde verilmeli, kullanıcının bunu kendisinin uygulayabilmesi için gerekecek ek şartlar belirtilmelidir.
Bilginin sadeleştirilmesi
Özellikle başlangıç kullanıcılarına yönelik bilgiler belli bir ayrıntı seviyesinin altına inemez. Fakat, okuyucunun, ayrıntılarını henüz öğrenemediği daha büyük bir dünyanın varlığından haberdar olması açısından, bir genelleme veya geçiştirme olduğu zaman, bu belirtilmelidir.
Örneğin DNS'in kabaca ne iş yaptığını anlatan bir belgede, DNS sorgularının arka planının çok ayrıntısına inilmesi uygun olmayabilir. Fakat bunu yerel DNS sunucusu ana DNS sunucusunu sorgular ve bilgiyi ondan alır demek yerine yerel DNS sunucusu ana DNS sunucusunu sorgular ve bilgiyi ondan alır (asıl sorgu mekanizması bundan biraz daha ayrıntılıdır, fakat bu belgenin kapsamı dışındadır) diye belirtmek, okuyucunun yanlış kavramlar oluşturmasını engeller.
Ek kaynaklar
Okuyucunun daha fazla bilgi için başvurabileceği (gerek Türkçe, gerek başka dillerde) kaynakları belirtmek faydalı bir işlemdir.
Dil
Çeviri belgeler için belirtilen dile özgü hususlar özgün belgeler için de geçerlidir.
Onay mekanizması
Özgün belgelerde:
  1. Hedef kitle için uygunluk.
  2. Genel akıcılık.
  3. Verilen bilgilerin doğruluğu.
aranır. Özellikle verilen bilgilerin doğruluğu, eğer bu konuda bilgiye sahip bir çalışma grubu üyesi yok ise, sorun doğurabilir. Böyle durumlarda belge yayınlanır.
Düzeltme/Ekleme
Herhangi bir belgeye gelen düzeltmeler, eklemeler, belli bir zaman aralığında gerçekleştirilmelidir. Kamusal ortamda, bireylerin ortak bilgi kümesinden faydalanma ve bir kişinin ortaya çıkaramayacağı derinlikte ve genişlikte belge üretilmesi ancak bu şekilde gerçekleşebilir.
Herhangi bir belge yazarı, belgesini yayınlanmak üzere gönderdiği zaman peşinen bu ekleme ve düzeltmeleri kabul etmiştir.
Ekleme ve düzeltmelerde bulunan kişilerin adları, katkının ne olduğuna dair ufak bir not ile belgenin başında yazar bölümünde yayınlanır. Belgenin içerisinde bu katkıları ayrıca farklı gösterilmez, işaret edilmez.  Pek çok kişinin katkı ve eklemesi olan bir belgede, okuyucu yormaksızın tek bir belge ortaya çıkarabilmek ancak bu şekilde mümkün olacaktır.
Ekleme ve düzeltmeler çalışma grubunun belirleyeceği kurallar dahilinde, çalışma grubunun atayacağı bir editör aracılığı ile yapılabileceği gibi, belgenin ilk yazarı/çevirmeni de bu işi üstlenebilir.
Burada esas, bu ekleme ve düzeltmelerin katkıda bulunmak isteyen kişinin şevkini kırmayacak bir zaman aralığında gerçekleştirilmesidir.
Bu süreç, belgenin doğruluğunu değerlendirmek açısından da, genelin bilgi kümesinden faydalanmak yolunu açacağından dolayı, belgelerin doğru, faydalı ve güncel kalmasını sağlayacaktır.
Önceki Üst Ana Başlık Sonraki
Ne NASIL yapılır? Başlangıç Linux Belgeleri NASIL
Bir Linux Kitaplığı Sayfası