Yazılım Dokümantasyonu Nedir? Başlamak İçin Türler ve En İyi Uygulamalar

Geliştiricilerin ve son kullanıcıların yazılımınızdan olabildiğince fazla değer elde etmesini istiyorsanız, yüksek kaliteli yazılım belgeleri oluşturmanız gerekir.

Ancak yazılım dokümantasyonu gerçekte nedir ve onu projeniz için nasıl oluşturabilirsiniz?

Bu gönderide, aşağıdakiler de dahil olmak üzere yazılım belgeleri hakkında bilmeniz gereken her şeyi derinlemesine inceleyeceğiz:

• Yazılım dokümantasyonu nedir?
• Farklı yazılım belgeleri türleri (örneklerle birlikte)
• Yazılım belgelerinizi nasıl yayınlayabilirsiniz (en iyi araçlar)
• Kaliteli yazılım belgeleri oluşturmak için bazı en iyi uygulamalar

Hadi kazalım!

Yazılım Dokümantasyonu Nedir?

Yazılım belgeleri, son kullanıcıların, geliştiricilerin ve/veya çalışanlarınızın yazılımınızı anlamasına ve hedeflerine etkili bir şekilde ulaşmak için kullanmasına yardımcı olan içeriktir.

Tipik olarak, yazılım belgelerini web sitenizde yayınlarsınız. İnsanlar daha sonra yazılımınız ve nasıl çalıştığı hakkında daha fazla bilgi edinmek için ona erişebilir.

Yazılım belgelerinin bu geniş tanımı içinde, farklı yazılım belgeleri türleri vardır. Bunu sonra tartışalım.

Farklı Yazılım Dokümantasyonu Türleri

Farklı türde yazılım belgelerini kabaca birkaç geniş kategoriye ayırabilirsiniz.

İlk husus, belgelerin ne tür bir kişiye yönelik olduğudur:

• Kullanıcı belgeleri – bu, ürünün son kullanıcısı için oluşturduğunuz belgelerdir. Herhangi bir özel teknik bilgiye sahip olsun ya da olmasın, normal bir kullanıcının bakış açısıyla yazılımınızı nasıl kullanacaklarını anlamalarına yardımcı olur.
• Geliştirici belgeleri – bu, geliştiriciler için oluşturduğunuz API belgeleri gibi daha teknik yazılım belgeleridir.

İkinci husus, dokümantasyonun harici veya dahili kitlelere yönelik olup olmadığıdır:

• Harici yazılım belgeleri – bu, kullanıcılarınıza yardımcı olmak için oluşturduğunuz halka açık belgelerdir.
• Dahili yazılım belgeleri – bu, çalışanlarınızın daha verimli çalışmalarına ve önemli ayrıntıları anlamalarına yardımcı olmak için oluşturduğunuz özel belgelerdir.

Örneğin, dahili ekiplerinizin yazılım üzerinde çalışmasına yardımcı olması için bir dizi geliştirici belgeniz ve harici geliştiriciler için başka bir halka açık geliştirici belgeleriniz olabilir.

Bu tür yazılım belgelerini biraz daha ayrıntılı olarak inceleyelim…

Geliştirici Dokümantasyonu için Yazılım Dokümantasyonu Örnekleri

• API belgeleri – geliştiricilere yazılımınızın API'si ile nasıl etkileşim kuracaklarını gösterin.
• Beni oku – yazılımınızı tanıtın ve ne işe yaradığını açıklayın – genellikle insanların okuduğu ilk şey.
• Sürüm notları – önemli değişiklikler de dahil olmak üzere yazılımınızın yeni sürümlerini belgeleyin.
• Mimari belgeleri – potansiyel olarak diyagramlar da dahil olmak üzere yazılımınızın yapısını gösterin.
• Veri modeli belgeleri – farklı veri yapıları arasındaki ilişkiler de dahil olmak üzere yazılımınızdaki farklı veri yapılarını belgeleyin.
• Süreç belgeleri – hata raporları, yol haritaları, kalite güvencesi, test protokolleri vb. gibi önemli süreçleri belgeleyin.

Geliştirici odaklı dokümanların gerçek bir yazılım dokümantasyonu örneği için, Gravity Forms'un aşağıdakiler gibi çeşitli konuları kapsayan “Geliştiriciler” dokümantasyonuna bakabilirsiniz:

• PHP kancaları (WordPress için)
• veri nesneleri
• PHP API'si
• Veri tabanı
• DİNLENME API'SI

Örneğin, REST API belgeleri şöyle görünür:

Kullanıcı Dokümantasyonu için Yazılım Dokümantasyonu Örnekleri

• Başlarken kılavuzu – kullanıcılara yazılımınızı nasıl hızlı bir şekilde kullanmaya başlayacaklarını gösterin.
• Belirli kullanım durumları için öğreticiler – belirli görevleri gerçekleştirmek için daha özel öğreticiler.
• Terim sözlükleri/referans kılavuzları – kullanıcıların temel terimleri ve ayrıntıları anlamalarına yardımcı olur.
• SSS - sık sorulan soruları yanıtlayın.

Daha kullanıcı odaklı yazılım belgelerinin nasıl görünebileceğine dair gerçek bir örnek için, yukarıdan aynı Gravity Forms örneğine dönebilirsiniz.

Gravity Forms'un daha kullanıcı odaklı makalelerine bakarsanız, sözlükler ve temel özelliklerin açıklamalarının yanı sıra, yazılım arabirimini kullanarak görevlerin nasıl gerçekleştirileceğine ilişkin birçok adım adım öğretici göreceksiniz.

Geliştirici yazılımı belgelerine kıyasla, daha fazla ekran görüntüsü ve sade dil açıklamaları ve çok daha az kod bloğu göreceksiniz.

Yazılım Dokümantasyonu Nasıl Yayınlanır: En İyi Üç Yazılım Dokümantasyon Aracı

Yazılım belgelerinizi web sitenizde yayınlamak için özel bir yazılım belgelendirme aracı veya bir tür bilgi yönetim sistemi isteyeceksiniz.

Bu bölümde, en iyi yazılım belgeleme araçlarından bazılarını hızlı bir şekilde ele alacağız. Ardından, bir sonraki bölümde, kalite belgeleri oluşturmak için bazı en iyi uygulamaları gözden geçireceğiz.

Burada daha derin bir inceleme yapmak isterseniz, en iyi dokümantasyon araçları ve en iyi teknik dokümantasyon yazılımı hakkındaki tüm kılavuzlarımızı okumak isteyebilirsiniz.

Kahramanca Bilgi Bankası

Heroic Knowledge Base, popüler açık kaynaklı WordPress yazılımı için bir belgeleme ve bilgi tabanı eklentisidir.

Heroic Knowledge Base ile, etkili yazılım belgeleri oluşturmak için ihtiyaç duyduğunuz tüm özelliklere erişmeye devam ederken, belgelerinizi kendiniz barındırabilir ve tam kontrol sağlayabilirsiniz.

Heroic Knowledge Base ile elde ettiğiniz temel özelliklerden bazıları şunlardır:

• Belirtme çizgileri ve diğer önemli stil ayrıntıları için yerleşik bloklar içeren esnek içerik düzenleyici .
• Kullanıcıların bir dokümantasyon makalesinde hangi içeriğin kapsandığını hızlı bir şekilde görebilmesi ve belirli bölümlere atlayabilmesi için otomatik içindekiler tablosu .
• Yerel WordPress revizyon sistemi aracılığıyla revizyon kontrolü ve sürüm geçmişi .
• Canlı öneriler, kategoriler ve daha fazlası ile gerçek zamanlı Ajax aramasını içeren içerik keşif özellikleri .
• İnsanların makaleleri yararlı veya yararsız olarak derecelendirmesine ve geri bildirim paylaşmasına olanak tanıyan kullanıcı geri bildirim sistemi .
• Kullanıcıların ne aradığını ve sıfır sonuç döndüren tüm arama terimlerini görebilmeniz için analizleri arayın .
• Kullanıcıların sitenizdeki herhangi bir yerden yazılım belgelerini aramasına ve bunlara erişmesine olanak tanıyan anında yanıtlar widget'ı .

Heroic Knowledge Base ve WordPress hem kendi kendine barındırılan hem de açık kaynak olduğundan, kurulumunuzu gerektiği gibi değiştirmekte de özgürsünüz.

Parolalar, kullanıcı hesapları, IP adresleri, bir intranet ve daha fazlası gibi çeşitli taktiklerle belgelerinize erişimi halka açık hale getirebilir veya erişimi kısıtlayabilirsiniz.

Heroic Knowledge Base yılda sadece 149 dolardan başlıyor.

Dokümanları Oku

Belgeleri Oku, geliştirici belgeleri oluşturmanıza yardımcı olmaya odaklanan bir belgelendirme aracıdır.

Özellikle teknik geliştirici belgeleri oluşturmaya odaklanıyorsanız, dikkate alınması gereken başka bir iyi seçenek olabilir.

İçeriğinizi ve düzeltme geçmişinizi Git'i kullanarak yönetebilir ve ardından dokümanlarınızı bir ön uç arayüzüne dağıtabilirsiniz.

Belgeleri Oku'daki diğer önemli özelliklerden bazıları şunlardır:

• Kullanıcılarınızın ne okuduğunu ve aradığını görmek için yerleşik analitik .
• Yazılımınızın birden çok sürümünü sunuyorsanız yardımcı olabilecek birden çok eşzamanlı yapıyı destekler - örneğin, sürüm 1.0 için bir belge seti ve sürüm 2.0 için bir tane daha.
• Belgeleri PDF, HTML ve epub dahil olmak üzere farklı biçimlerde dışa aktarın .
• Kullanıcıların belgeleri bulmasına yardımcı olacak canlı arama önerileri.

Açık kaynaklı bir yazılım projeniz varsa Dokümanlar'ı okumak ücretsizdir.

Ticari yazılım ürünleri için, aylık 50 dolardan başlayan ücretli bir İş İçin Dokümanları Oku hizmeti vardır.

GitKitap

GitBook, hem GitHub hem de GitLab havuzları desteğiyle belgelerinizi Git'i kullanarak yönetmenize izin veren başka bir teknik yazılım belgelendirme aracıdır.

Veya Git'i kullanmak istemiyorsanız, GitBook belgelerinizi bir metin düzenleyici kullanarak oluşturmanıza veya onu markdown veya .doc dosyalarından içe aktarmanıza da olanak tanır.

İşte GitBook'un sunduğu diğer bazı önemli özellikler:

• Revizyonları ve sürüm geçmişini takip etmek için sürüm kontrolü .
• Birden çok yazarın makaleler üzerinde işbirliği yapması gerekiyorsa yararlı olan canlı ekip düzenlemesi .
• Makaleleri "boşluklar" ve "koleksiyonlar" kullanarak düzenleyin - her alanın içinde birden fazla koleksiyon olabilir.
• Kullanıcıların belgelerinizi bir PDF indirmesi olarak kolayca dışa aktarabilmeleri için PDF dışa aktarma seçeneği.

GitBook, kar amacı gütmeyen veya açık kaynaklı projeler için ücretsizdir.

Ticari yazılım projeleri için GitBook, en az 5 kullanıcı ile kullanıcı başına aylık 8 ABD dolarından başlar. Bu, en ucuz aylık oranın ayda 40 ABD Doları olduğu anlamına gelir.

Yazılım Dokümantasyonu Oluşturmak İçin En İyi Uygulamalar

İşleri bitirmek için, etkili belgeler oluşturmanıza yardımcı olacak bazı yazılım belgeleri en iyi uygulamalarını inceleyelim.

Kullanıcıların Hedeflerini ve İhtiyaçlarını Düşünün

Bir yazılım dokümantasyonu makalesi yazarken, birkaç temel soruyu yanıtlayarak başlamak önemlidir:

• Yazdığınız kullanıcı kim?
• Kullanıcı neyi başarmaya çalışıyor?
• Kullanıcının ne düzeyde teknik bilgisi var?

Bu soruların cevaplarını bilmek, hangi içeriği ele alacağınızı ve makaleyi en uygun şekilde nasıl yapılandıracağınızı anlamanıza yardımcı olacaktır.

Örneğin, sosyal medya planlama yazılımı sunduğunuzu ve sosyal medya yöneticilerinin ilk sosyal medya gönderilerini planlamalarına yardımcı olan bir makale yazdığınızı varsayalım.

Yazılım belgelerinizi yazarken, normal bir son kullanıcının bu hedefi gerçekleştirmesi için en basit yolu göstermeye odaklanmak istersiniz.

Ayrıca, geliştiricilerin kendi entegrasyonlarını kurmalarına olanak tanıyan bir API sunuyorsanız, muhtemelen bunu farklı bir makalede ele almak istersiniz ( yine de bu yöntemden bahsedebilir ve bu yönteme bağlantı verebilirsiniz ).

Yazılım Belgelerini Geliştirme Sürecine Dahil Edin

Yazılım belgeleri oluştururken, bir projeyi belgelemek için tamamlanana kadar bekleme tuzağına düşmek kolaydır.

Ancak, yeni özellikleri veya değişiklikleri belgelenmeden önce gönderiyor olabileceğiniz için bu, hızlı bir şekilde belgelendirme borcuna yol açabilir.

Bundan kaçınmak için, yazılım dokümantasyonunu yazılım geliştirme döngüsünün bilinçli bir parçası yapın. Henüz yeni bir özellik veya ürün belgelenmemişse, kodun kendisi bitse bile gönderilmeye hazır değildir.

Dokümantasyonu yazılım geliştirme sürecinin temel gereksinimi haline getirerek, gönderdiğiniz her şeyin uygun dokümantasyonla birlikte olmasını sağlayabilirsiniz.

Tutarlı Biçimlendirme ve Stil Kullanın

İnsanların yazılım belgelerinizle daha verimli çalışmasına yardımcı olmak için tüm belgelerinizde tutarlı biçimlendirme ve stil kullanmanız önemlidir.

Aynı biçimlendirmeyi kullanmak, okuyucuların yazılım belgelerinizin nasıl yapılandırıldığını öğrenmelerine olanak tanır ve bu da ihtiyaç duydukları bilgilere hızla erişmelerini kolaylaştırır.

Bu tutarlılığı sağlamaya yardımcı olması için, özel bir yazılım dokümantasyon stili kılavuzu oluşturmak isteyebilirsiniz.

Yazılım dokümantasyon yönetimi aracınız, tutarlı stil elde etmenize yardımcı olacak özellikler de içerebilir.

Örneğin, Heroic Knowledge Base eklentisi, önemli bilgileri veya uyarıları vurgulamak için önceden biçimlendirilmiş açıklamalar içerir. Bunları kullanarak, tüm belgelerinizde tutarlı biçimlendirme sağlayabilirsiniz.

Teknik Dokümantasyon Yazmak İçin Uzmanları Kullanın

Kullanıcıya yönelik yazılım belgeleri için, içeriği yazmak üzere konu uzmanlarına ihtiyacınız olmayabilir.

Ancak, geliştirici odaklı API belgeleri gibi daha teknik yazılım belgeleri için, ilgili teknik bilgiye sahip birini bu belgeleri yazması için görevlendirmek isteyebilirsiniz.

Kuruluşunuz bu pozisyon için işe alacak kaynaklara sahipse, bu, alan uzmanlığına sahip özel bir teknik yazar olabilir. Veya geliştiricilerinizden biri olabilir.

Önemli olan, yazarın yazılımınızın teknik yönlerini diğer teknik kullanıcılara açıklayacak kadar derin bir düzeyde anlamasıdır.

İnsanların İçeriği Keşfetmesini Kolaylaştırın (Arama/Filtreleme)

Dokümantasyon kitaplığınız büyüdükçe, kullanıcıların ihtiyaçlarını karşılayan dokümantasyon makalelerini bulması zorlaşacaktır.

Bu sorundan kaçınmaya çalışmak için, yazılım belgelerinizin keşfedilebilirliğini artırmaya odaklanmak isteyeceksiniz.

İlk strateji, belgelerinizi türe göre bölmektir.

Örneğin, genellikle son kullanıcı belgelerinizi geliştirici yazılımı belgelerinden ayırmak isteyeceksiniz.

Bunun içinde, makaleleri daha fazla bölmek için kategorileri de kullanabilirsiniz. Özelliklere, kullanım durumlarına, eklentilere vb. dayalı kategorileri kullanabilirsiniz - yazılım ürününüz için mantıklı olan ne olursa olsun.

Yukarıdaki Gravity Forms örneğine uygun olarak, Gravity Forms'un son kullanıcı belgelerini özellik tiplerine göre böldüğünü görebilirsiniz.

Bir başka yararlı keşfedilebilirlik özelliği, canlı arama önerileridir. Kullanıcılar, arama kutusuna ilgili bir sorgu yazmaya başlayabilir ve bu sorguyla eşleşen belge makalelerini anında görebilir.

Birçok dokümantasyon aracı, Heroic Knowledge Base dahil olmak üzere yerleşik canlı arama işlevi içerir.

Yazılım Belgelerinizi Güncel Tutun

Yazılımınız sürekli değiştiğinden, yazılım belgeleriniz her zaman devam eden bir çalışma olacaktır.

Yazılımınızda bir şeyler değiştikçe, belgelerinizi bu değişiklikleri yansıtacak şekilde hemen güncellemeniz gerekecektir.

Aksi takdirde, belgeleriniz yalnızca "faydalı" olmayacak, aynı zamanda kullanıcılarınızda kafa karışıklığı yaratıyor olabilir.

Bu güncellemelerin yapıldığından emin olmak için, dokümantasyon ve güncelleme sürecinin sahibi olacak belirli kişileri atamak isteyeceksiniz. Bu şekilde, her şeyi doğru tutmaktan kimin sorumlu olduğu konusunda bir belirsizlik olmaz.

Belgelerinizi Geliştirmek İçin Müşteri Geri Bildirimlerini Kullanın

Yazılım belgelerinizi gözden geçirmek ve güncellemek için kendi ekibinizin çalışmasına ek olarak, müşteri geri bildirimlerini de dikkate almak isteyeceksiniz.

Müşteriler, belirli bir yazılım dokümantasyonu makalesinin ne kadar yararlı (veya potansiyel olarak yararsız) olduğu ve onu nasıl iyileştirebileceğinize ilişkin ayrıntılar hakkında değerli bilgiler sağlayabilir.

Müşteri geri bildirim sürecini otomatikleştirmek için, müşteri geri bildirimi için yerleşik özellikler içeren bir dokümantasyon yönetim aracı aramak isteyeceksiniz.

Örneğin, Heroic Knowledge Base eklentisi, kullanıcıların bir makaleyi yararlı veya yararsız olarak derecelendirmesine ve ayrıca isteğe bağlı olarak serbest biçimli geri bildirim sağlamasına olanak tanır.

Daha sonra, geliştirmeniz gereken dokümantasyon makalelerini hızlı bir şekilde belirlemek için kontrol panelinizden tüm bu bilgileri görüntüleyebilirsiniz.

Yazılımınızı Belgelemeye Bugün Başlayın

Yazılım belgeleri, sizin ve müşterilerinizin daha verimli çalışmasına ve yazılımınızdan daha fazla değer elde etmenize yardımcı olur.

Farklı türlerde yazılım belgeleri vardır, bu nedenle hangi türlerin yazılım projenizin gereksinimlerine uygun olduğunu düşünmek isteyeceksiniz.

Dahili veya harici ekiplerin yanı sıra geliştiriciler ve son kullanıcılar gibi farklı müşteri türleri için farklı belgeleriniz olabilir.

Etkili belgeler oluşturmak için bu gönderideki en iyi uygulamaları takip etmek isteyeceksiniz.

Bu belgeleri yayınlamak için, güçlü WordPress yazılımını temel alan Heroic Knowledge Base gibi açık kaynaklı bir araç kullanabilirsiniz.

Yüksek kaliteli yazılım belgeleri yayınlamak için ihtiyaç duyduğunuz tüm özellik ve işlevlerle birlikte, kendi kendine barındırılan bir platformun esnekliğine ve sahipliğine sahip olacaksınız.

Daha fazlasını öğrenmek istiyorsanız, Heroic Knowledge Base'e gitmek için buraya tıklayın.