İyi Belgeler Yazma Üzerine Bir Başlangıç

Bu gönderiye konuk yazar Jeff Matson katkıda bulunmuştur. Jeff, GravityForms'un dokümantasyon başkanıdır. Heartbeat Control WordPress eklentisinin yaratıcısı ve 90'ların hayranı.

Çoğu zaman, dokümantasyon geliştirme sürecinin en önemsiz parçasıdır. WordPress topluluğundaki rock yıldızlarına baktığımızda genellikle geliştiricilere, tasarımcılara ve pazarlamacılara bakarız. Her şeyin yolunda gitmesini sağlamak için kanını, terini ve gözyaşını döken belge yazarları hakkında çok az şey biliniyor.

Bu gönderi, geliştiricinin ne düşündüğünü ve var olan kodun arkasındaki gerçek anlamı deşifre etmek için her gün sonsuz kod satırlarına bakan kişiler hakkındadır.

İyi Belgeler Kelimelerden Daha Fazlasıdır

İyi belge yazarları, bir kullanım kılavuzundan daha fazlasını sağlar, bir deneyim sağlar. Mükemmel belgeleyiciler, koçluk yapan yeni başlayanlar tanıdım ve aralarındaki en büyük fark, onu okuyanların beynini anlamaktır. Tıpkı bir roman gibi, belgelerin de okuyucunun ilgisini çeken ve fark ettiğinden daha fazla bilgi almasını sağlayan bir akışı vardır.

Kaliteli belgeler, onu okuma olasılığı en yüksek olan kullanıcıları hedefler. Ayrıca okuması daha olası olmayanlar için bir referans noktası sağlar. Örneğin, belirli bir kanca belgeleniyorsa, genellikle bir geliştiricinin onu okuyacağı varsayılır, peki ya geliştirme deneyimi az olanlar?

İyi bir dokümantasyon yazarı, doğru yönde daha fazla itmeye ihtiyaç duyanlar için, onları hecelemek için desteğe başvurmaya gerek kalmadan bir referans noktası sağlayacaktır.

Belgelemenin Etkisi Düşündüğünüzden Daha Büyük

Çoğu, belgeleri görmezden gelerek, artık dayanamayacak hale gelene kadar sonsuz uçuruma iter. Bazı durumlarda ben de aynı şeyden suçluyum. Bu insanların fark etmedikleri şey, eklentilerinin veya temalarının belgelenmeden bırakıldığı her an, kullanıcı deneyiminin zarar görmesidir.

En yaygın destek biletinize bir göz atalım. Bu sorunu daha iyi belgeleseydin, bu biletler tamamen ortadan kalkar mıydı? Muhtemelen değil. Sizin veya destek temsilcinizin üretkenliğini artırmanın yanı sıra konuyla ilgili daha az bilet alır mısınız? Garanti veriyorum. Sanırım hepimiz daha az destek bileti kullanabiliriz.

Daha önce de belirttiğim gibi, dokümantasyon kullanıcı deneyimi üzerinde çarpıcı bir etki yapar. Kullanıcı bilgiyi kolay ve verimli bir şekilde bulabilirse, hem kendi zamanını hem de sizin zamanınızdan tasarruf etmiş olur. Ortalama dünya ömrü 66,57 yıldır ve kullanıcılarınız kötü yazılmış belgelerle uğraşmaktansa hayatlarıyla başka bir şey yapmayı tercih eder.

Bir müşteri, belgelerinize oldukça fazla zaman ve emek harcadığınızı görürse, bilinçli olsun ya da olmasın, sizi daha iyi takdir edecektir. İyi belgeler, ilk satıştan sonra onları önemsediğinizi gösterir.

Zor kazanılan parayı harcadıktan sonra hiç sarhoş ve kuru kaldınız mı ve satın aldığınız için kısa süre sonra pişman oldunuz mu? Sanırım hepimizde var. Doğru belgelerle, müşterilerinize bu hissi vermekten kaçınabilirsiniz.

Nasıl Daha İyi Belgeler Yazabilirsiniz?

İlk adım, bundan kaçınmayı bırakmaktır. Bir kez bu konuda iyi olduğunuzda, belge yazmak düşündüğünüzden daha zevkli bir deneyimdir. Aslında, ikinci doğa haline gelecektir. Tıpkı dünyadaki her şey gibi, pratik yapmak da mükemmelleştirir.

Belgelerinizi bir sonraki aşamaya taşımaya karar verirken atmanız gereken ilk adımlardan biri sorunlu noktalarınızı belirlemektir. Ne hakkında iletişime geçiyorsunuz? Bir şeyler hakkında körü körüne yazmaya başlarsanız, hakkında yazdıklarınızın istediğiniz kadar etki yaratmadığını görebilirsiniz.

Bulduğum en iyi tekniklerden biri, belgelenen biletlerin sayısı ile belgelenmeyen biletlerin sayısını izlemek ve olmayanları kategorilere ayırmak. Bu şekilde, ağrı noktalarınızı daha iyi hedefleyebilir ve olması gerektiği kadar yardımcı olmayabilecek kısımları revize edebilirsiniz.

Hangi belgeleri yazmanız gerektiğini belirledikten sonra hedef kitlenizi belirlemeli ve geliştiriciler, kullanıcılar ve ileri düzey kullanıcılar olarak ayırmalısınız. Bu, belirli bir kitleye hitap etmenize yardımcı olur. Bu kullanıcıları nasıl hedefleyeceğimizi biraz sonra ele alacağız.

Ardından, belgeyi parçalamak istiyorsunuz. Geliştiriciler için, onu ham bilgilere (kabul edilen argümanlar, dönüş değerleri vb.), özel örneklere ve kullanım durumlarına bölmek isteyeceksiniz. Kullanıcılar için en iyi hareket tarzı bir adım adım ilerlemedir. Ne kadar önemsiz görünse de, atmaları gereken her adım çok önemlidir.

Yolun her adımında onlara heceleyin. Uzman kullanıcılar için belgeleme, bir kullanıcı senaryosuna çok benzer, ancak daha yapılandırılmış ve taranabilir. Net olun, ancak önce önceki adımı okumadan gitmeleri gereken yere kolayca atlamalarına izin verin.

Daha İyi Belgeler Yazma Sanatı

Belgelerinizi yazma sanatı söz konusu olduğunda, hedef kitlenizi en iyi şekilde hedefleyecek şekilde yazın, ancak aynı zamanda anlayacaklarını bildiğiniz basit bir dil kullanın. Bunun en iyi nedenlerinden biri çevirilerden kaynaklanmaktadır. Google çeviri mükemmel bir iş çıkarsa da, bir 5. sınıf öğrencisinin basit kelime dağarcığını çevirmek, yüksek lisans tezinde yer alandan çok daha kolaydır.

İçeriğiniz içinde, alakalı içeriğe bağlantı vermekten korkmayın. Bu, birden fazla belgede kendinizi tekrar etmekten kaçınmanıza ve okuyucunun belirli bir konu hakkında daha fazla bilgiye ihtiyaç duyması durumunda geriye doğru izlemesine olanak tanır. Sonuçta asıl amacınız kullanıcıyı mutlu etmek ve kendinize zaman kazandırmak.

Yayımla düğmesine bastıktan sonra dokümantasyon süreci durmaz. Geri dönün ve her belgeyi gerektiği gibi gözden geçirin. Belge yayınlandıktan hemen sonra geri dönün ve takip ettiğiniz destek biletlerinin reddedilip reddedilmediğine ve söz konusu makaleye yönelik trafiğin artıp artmadığına bakın. Genellikle, bir makaleye daha fazla trafik alıyorsanız, bu yardımcı olur. Daha fazla trafik alıyorsanız ancak aynı sayıda destek bileti alıyorsanız, nedenini öğrenmek için bu makaleye bakmak isteyebilirsiniz.

Ne Öğrendik?

İlk olarak, umarım buraya kadar geldikten sonra, çoğumuzun doğal olarak kabul ettiği belgeleri yazan siperlerde olanlar için daha iyi bir takdiriniz olur. Gerçekten de, yaşamak için belgeler yazan çoğumuzun gerçekten zevk aldığı ve saatlerce harcadığı bir sanat biçimidir.

Ayrıca, mevcut belgeleriniz ve nasıl geliştirilebileceği hakkında daha fazla düşünerek bu makaleden uzaklaşacağınızı umuyorum. Doğru belgeler son derece ödüllendirici olabilir ve bir kez pratikte yazmak aslında oldukça eğlenceli olabilir.

Erken belgeleyin, sık sık belgeleyin. Harika bir ürün harika bir koddan daha fazlasıdır, ayrıca güzel bir şekilde belgelenmiştir.