WordPress eklentilerini ve temalarını belgeleme

Belgeleme, genellikle yalnızca bir sorun olduğunda ve hızlı yanıtlara ihtiyacınız olduğunda takdir edilen bir şeydir. Bu makalede, WordPress varlıklarınız için belge yazmanın bir WordPress geliştiricisi olarak uygulamanız için neden önemli olduğunun nedenlerini ve gönderdiğiniz temaların ve eklentilerin kalitesini inceleyeceğiz.

Dokümantasyon neden önemlidir?

Projeleriniz, varlıklarınız veya ürünleriniz hakkında güncel bir belge seti tutmak birçok nedenden dolayı önemlidir.

Birincisi, 2 ay önce yaptığınız ve o zamandan beri dokunmadığınız bir şeye bakmak ve bunun ne anlama geldiğini bilmemek yaygın bir deneyimdir. Onu geliştirdiğinizde her şey kafanızın içinde olur ama bu anlayış gelecekte orada olmayacak. Bu nedenle, Markdown'da satır içi kod yorumları kullanmak veya düz metin notları yazmak, gelecekteki benliğinizi kafa karışıklığından kurtarmada uzun bir yol kat eder.

İkincisi, varlıklarınızı belgelemek, diğer WordPress geliştiricileri için yararlıdır. Ve bu, yalnız bir serbest çalışan olsanız bile mantıklıdır (bir noktada diğer insanlarla işbirliği yapmak zorundasınız). Ya bu varlıkları kullanmaları gerekecek ya da bunları sürdürmeleri ve/veya güncellemeleri istenecektir. Destek sağlamak veya bazı zor noktaları açıklamak için etrafta olmayan başka biri tarafından yazılmış belgesiz kodu kullanmak çok sinir bozucu.

Son olarak, belgeler ürünlerinize "cilalı" bir görünüm katar ve müşterileriniz sizi daha çok sevecektir.

Etkili dokümantasyon için 5 ilke

Teknik yazı başlı başına bir disiplindir ve teknik bilgileri açık ve net bir şekilde iletmek için kullanılır. (Sadece bilgisayarlarla sınırlı değil, örneğin avukatlar ve doktorlar da kendi teknik dillerini kullanırlar). Bu nedenle teknik yazı olarak kabul edilen bir belge, genellikle belirli bir üslup izler ve bir takım kurallara uyar.

Ürünleriniz için etkili belgeler yazabilmeniz için en önemli 5 tanesine geçelim!

• Yazınızda normalde kullandığınızdan daha az kelime kullanmayı tercih edin: Her kelimenin bir amacı olmalıdır. Doğrudan ve basit olun. Belgeler genellikle bir kişinin başı dertte olduğunda ve hızlı bir şekilde bir çözüm bulmak istediğinde aranır. Örneğin, "Nesne Q'nun yok edilmemesi bellek sızıntılarına neden olacaktır" gibi bir cümle, "Nesne Q'nun yok edilmemesi bellek sızıntılarına neden olacaktır " yerine tercih edilir.
• Pasif yerine aktif ses kullanmayı tercih edin: “ Sağ üstteki düğmeye tıklanması gerekiyor ” yerine “sağ üstteki düğmeye tıklayın”. Aktif bir ses kullanmak, kimin ne yaptığına ilişkin belirsizlikleri ortadan kaldırır. Pasif ses, özne yerine yalnızca nesneye odaklanmanız gerektiğinde kullanılır (örneğin, Pressidium'un Platformu güvenlik düşünülerek oluşturulmuştur ) .
• Kavramları tanımlamanız gerektiğinde açıklayıcı dil kullanın ve adım adım bir prosedürü (eğitimler gibi) tanımlamanız gerektiğinde zorunlu kullanın.
• Sırası olmayan şeyleri listelemeniz gerektiğinde madde işaretli listeleri ve noktaların sırası önemli olduğunda numaralı listeleri kullanın.
• Talimatları sunmadan önce kendiniz test ettiğinizden emin olun!

WordPress eklentilerini belgeleme

WordPress eklentileri diğer yazılım parçaları gibidir. Belirli bir işlevsellik sağlarlar, kurulum gerektirirler ve bazen de sorun giderme. Ne kadar basit olursa olsun, tüm kullanıcılar aynı teknik uzmanlığı paylaşmadığından yeterli miktarda belge sağlamak her zaman iyi bir fikirdir.

Pressidium ile web sitenizi barındırın

60 GÜN PARA GERİ GARANTİSİ

PLANLARIMIZI GÖRÜN

WordPress eklentinizi wordpress.org'da yayınlamak size kurulum talimatlarını, ekran görüntülerini, SSS'yi ve hatta bir Değişiklik Günlüğünü koyabileceğiniz bir yer sağlayacaktır! Bunları faydalı ve kaliteli bilgilerle doldurmak, eklentinizi daha popüler hale getirmenin anahtarıdır:

• Sonunda kullanıcının eklentinizi indirmesini ve web sitenizi ziyaret etmesini sağlayacak ilgi çekici ve kullanışlı bir açıklama yazın.
• Eklentinizin tarayıcıda nasıl göründüğünü gösterenlere ek olarak eklentinizin her bir yapılandırma öğesini açıklayan açıklamalı ekran görüntüleri ekleyin.
• Sıkça sorulmayan soruları SSS'ye koyun. Garip uç durumları keşfetmenin iyi bir yolu, bilgisayar konusunda bilgili olmayan bir arkadaşınızdan eklentinizi kullanmasını istemektir.
• Güncellenmiş ve iyi yazılmış bir Changelog'a sahip olun. Kısa ve gizemli tek satırlar büyük bir hayır-hayırdır ve kullanıcılarınızı gerçekten umursamadığınızı gösterir.
• Eklentinizin kodunun iyi yorumlandığından ve en iyi yazılım uygulamalarına ve resmi kodlama standartlarına uyduğundan emin olun.

Sıkışmışsanız ve biraz ilhama ihtiyacınız varsa, küçük bir araştırma yapın ve metnin daha az kullanılanlara kıyasla yüz binlerce kuruluma sahip popüler eklentilerde nasıl yazıldığını görün.

WordPress temalarını belgelemek

WordPress temalarını belgelemek tamamen farklı bir konudur. WordPress temalarıyla ilgili en yaygın sorun, hangi bölümün hangi görsel öğeye karşılık geldiğini bilmemektir. Herkes CSS'de akıcı değildir:

• İlgili açıklamalarla birlikte CSS'nizin tüm bölümlerinden oluşan bir hiyerarşi oluşturun.
• Her bölüm için, küçük bir örnekle birlikte her bir işlevi detaylandıran açıklamalı bir ekran görüntüsü ekleyin. Kullanıcının talimatları izlemesini gerektiren bir şeyin nasıl yapılacağını gösterirken aktif ses ve emir dili kullanmayı unutmayın.
• Size yardımcı olması için css_doc gibi bir araç kullanın. Bu, bir JavaDoc stili belge oluşturur ve yayınlanabilir.
• Bazen kod yorumları yeterli olmaz ve CSS temanız için bir Stil Kılavuzu belgesi oluşturmanız gerekir. Stil kılavuzu belgeleri, öğelerin nasıl görünmesi gerektiğini ve hangi durumlarda kullanılması gerektiğini açıklar. Tutarlılığı zorlarlar ve işbirliğini de kolaylaştırırlar. Google'ın sunduğu bu örneğe bakın.
• Blueprint CSS gibi bir CSS çerçevesi kullanın. Bu, size özelleştirilebilir ızgara, çalışan varsayılan tipografi, tarayıcı CSS sıfırlama ve çok daha fazlası gibi bir dizi araç sağlayarak geliştirmede size yardımcı olacaktır.
• Yine, resmi WordPress CSS kodlama standartlarına başvurmayı unutmayın.