Geliştiriciler Neden Dokümanları Atlamamalısınız

Mobil uygulamalar, web uygulamaları, masaüstü uygulamaları veya JavaScript kitaplıklarının geliştirme alanında dokümantasyon, yazılımın geliştirme başarısını belirleyebilecek önemli bir rol oynar. Ancak, hiç dokümantasyon yaptıysanız, geliştiricilerin yapması en az sevilen şeyler olduğu konusunda benimle aynı fikirde olacaksınız..

Yazma kodunun aksine (geliştiricilerin kaydettikleri şey), dokümantasyon (yapmadığımız) tarafından kolayca sindirilebilir ve sindirilmeli. herkes. Teknik olarak, bir makine dilini (kodunu) insanlar için anlaşılır bir dil olana çevirmeliyiz..

Gerçek bir külfetli olsa da, dokümantasyonu yazmak önemlidir ve kullanıcılarınız, meslektaşlarınız ve özellikle kendiniz için avantajlar sağlayacaktır..

İyi Belgeler Kullanıcılara Yardımcı Olur

Belgeler okuyucuya yardımcı olur bir kodun nasıl çalıştığını anlayın, Açıkçası. Ancak birçok geliştirici yazılım kullanıcılarının yetkin olacağını varsaymakta hata yapar. Bu nedenle, belgeler baştan itibaren sahip olması gereken temel unsurları atlayarak ince malzeme olabilir. Dil konusunda bilgili iseniz, kendi inisiyatifinize göre işleri çözebilirsiniz; eğer değilseniz, o zaman kaybolursunuz.

Kullanıcılara yönelik belgeler genellikle pratik kullanımdan veya “nasıl”. Genel kullanıcılar için dokümantasyon oluştururken dikkat edilmesi gereken kural şudur: kesin olmalı. İnsan dostu kelimeler kullanmak, teknik terimler veya jargonlara tercih edilir. Gerçek kullanım örnekleri de çok takdir edilecektir.

İyi bir düzen tasarımı, kullanıcıların dokümantasyonun her bölümünü göz yorgunluğu olmadan taramasına da yardımcı olur. Birkaç iyi örnek (favorilerim gibi) Bootstrap ve WordPress'in dokümantasyonu. “WordPress ile İlk Adımlar”.

Diğer Geliştiricilere de Yardımcı Olur

Her geliştiricinin kendi kodlama stili olacaktır. Ancak, bir takımda çalışmak söz konusu olduğunda, kodları diğer takım arkadaşlarıyla paylaşmak zorunda kalacağız. Bu yüzden önemlidir standart üzerinde fikir birliği yapmak herkesi aynı sayfada tutmak için. Doğru yazılmış bir dokümantasyon ekibin ihtiyaç duyduğu referans olacaktır.

Ancak, son kullanıcı dokümantasyonundan farklı olarak, bu dokümantasyon genellikle teknik prosedürler Kod adlandırma kuralı gibi, belirli sayfaların nasıl oluşturulması gerektiğini ve API'nin kod örnekleriyle birlikte nasıl çalıştığını gösterir. Genellikle, belgelere kodla aynı zamanda yazmamız gerekir (kod olarak da bilinir). yorumlar) Kodun ne yaptığını açıklamak.

Ayrıca, bulunduğunuz durumda yeni üyeler Ekibiniz daha sonra, bu belgeler onları eğitmek için etkili bir yol olabilir, bu nedenle kodları üzerinde bire bir çalıştırmaları gerekmez..

Garip Bir Şekilde Kod Yazıcısına Yardımcı Olur

Kodlamanın komik yanı, bazen geliştiricilerin kendisi bile yazdıkları kodu anlamıyor. Bu, özellikle kodların aylarca hatta yıllarca dokunulmadığı durumlarda geçerlidir..

Bir nedenden ötürü kodları tekrar gözden geçirme ihtiyacı, bu kodları yazarken akıllarında neler olup bittiğini merak eder. Şaşırmayın: Daha önce bu durumda bulundum. Bu tam ne zaman ben diledi Kodumu doğru belgeledim.

Kodlarınızı belgeleyerek, kodlarınızın altına hızlı ve sıkıntı yaşamadan erişebilecek ve değişikliklerin yapılmasında harcayabileceğiniz zamanın büyük kısmını azaltabileceksiniz..

İyi Belgelendirme İçin Neler Yapar??

İyi bir dokümantasyon parçası oluşturmak için birkaç faktör vardır..

1. Asla Varma

Kullanıcılarınızın ne olduğunu bildiğini sanmayın. sen ne kadar iyi biliyorsan onlar bilmek istiyorum. Her zaman daha iyi en baştan başlamak kullanıcıların yeterlilik seviyesinden bağımsız olarak.

Örneğin, bir jQuery eklentisi oluşturduysanız, SlickJS'in dokümantasyonundan ilham alabilirsiniz. HTML’nin nasıl yapılandırılacağını, CSS’in ve JavaScript’in nereye yerleştirileceğini, jQuery eklentisinin en temel seviyede nasıl başlatılacağını ve hatta tüm açık olan şeylerin eklenmesinden sonra son işaretlemenin tamamını gösterdiğini gösterir..

Alt satırda dokümantasyon bir geliştirici değil, bir kullanıcının düşünce süreci ile yazılmıştır. Kendi belgelerinize bu şekilde yaklaşmak, kendi eserinizi düzenlemede size daha iyi bir bakış açısı sağlayacaktır..

2. Standardı takip edin

Kodla aynı çizgiye giden belgeler eklerken, dilden beklenen standardı kullanmak. Her bir fonksiyonu, değişkenleri ve fonksiyonun döndürdüğü değeri tanımlamak her zaman iyi bir fikirdir. İşte PHP için iyi bir satır içi dokümantasyon örneği.

 / ** * Özel sınıfları vücut sınıfları dizisine ekler. * * @param array $ classes Vücut elemanı için sınıflar. * @return array * / function body_classes ($ classes) // 1'den fazla yayınlanmış yazarı olan bloglara bir grup blog sınıfı ekler. if (is_multi_author ()) $ classes [] = 'grup blogu';  $ return sınıfları;  add_filter ('body_class', 'body_classes');

PHP, JavaScript ve CSS'deki en iyi uygulamalarla satır içi belgelerin biçimlendirilmesi için birkaç referans:

PHP: WordPress için PHP Belgelendirme Standardı
JavaScript: UseJSDoc
CSS: CSSDoc

SublimeText kullanıyorsanız, kodunuzu zekice önceden yerleştirilmiş belgelerle önceden dolduracak olan DocBlockr'ı yüklemenizi öneririm.

3. Grafik öğeler

Grafik elemanlar kullanın, metinden daha iyi konuşurlar. Bu ortamlar özellikle grafik arayüze sahip bir yazılım oluşturuyorsanız yararlı olur. Ok, daire veya Kullanıcıların, adımları tahmin etmeksizin, tahminde bulunmadan nereye gideceklerini bulmalarına yardımcı olabilecek herhangi bir şey.

Aşağıdakiler, ilham alabileceğiniz Tower uygulamasından bir örnektir. Sürüm kontrolünün nasıl olduğunu, düz metin komut satırları kullanmaktan daha anlaşılır kılan, hoş bir şekilde nasıl çalıştığını etkili bir şekilde açıklarlar..

4. Bölümleme

Madde imli listelerin ve tabloların içindeki belgelere bir kaç şeyi sarmayı düşünebilirsiniz; çünkü bu, içeriğin kullanıcılar için daha kolay taranmasını ve okunmasını kolaylaştırır..

Bir içerik tablosu ekleyin ve belgeleri kolayca sindirilebilir bölümlere ayırın, ancak her bölümü daha sonra gelenlerle ilgili tutun. Kısa ve açık tutun. Aşağıda Facebook'taki güzel organize edilmiş belgelere bir örnek verilmiştir. İçindekiler bizi bir tıkla atlamak istediğimiz yere götürüyor.

5. Gözden Geçir ve Güncelle

Son olarak, hataların belgelerini gözden geçirin ve gerektiğinde veya ürün, yazılım veya kütüphanede önemli değişiklikler olduğunda bunları gözden geçirin. Belgeniz, ürününüzle birlikte düzenli olarak güncellenmezse, kimseye yararı olmaz.