İyi yazılım belgeleri, ister programcılar ve testçiler için spesifikasyon belgeleri, ister dahili kullanıcılar için teknik belgeler veya son kullanıcılar için kılavuzlar ve yardım dosyaları olsun, kullanıcıların yazılımın özelliklerini ve işlevlerini anlamalarına yardımcı olacaktır. İyi dokümantasyon, kullanıcının ihtiyaç duyduğu tüm bilgilerle birlikte spesifik, açık ve alakalı dokümantasyondur. Bu makale, teknik kullanıcılar ve son kullanıcılar için yazılım belgeleri yazmanıza rehberlik edecektir.
Adım
Yöntem 1/2: Teknik Kullanıcılar için Yazılım Belgeleri Yazma
Adım 1. Hangi bilgileri dahil edeceğinizi bilin
Spesifikasyon belgesi, arayüz tasarımcıları, kod yazan programcılar ve yazılım performansını doğrulayan testçiler için bir başvuru kılavuzu olarak kullanılır. Dahil edilmesi gereken bilgiler, oluşturulan programa bağlı olacaktır, ancak aşağıdakileri içerebilir:
- Geliştirme ekibi tarafından oluşturulan dosyalar, program çalışırken erişilen veritabanları ve üçüncü taraf uygulamalar gibi uygulamadaki önemli dosyalar.
- Fonksiyon/alt rutin, giriş ve çıkış değerlerinin kullanımına ilişkin bir açıklama da dahil olmak üzere fonksiyonlar ve alt rutinler.
- Program değişkenleri ve sabitleri ve bunların nasıl kullanıldığı.
- Genel program yapısı. Sürücü tabanlı programlar için her bir modülü ve kitaplığı tanımlamanız gerekebilir. Veya web tabanlı bir program için bir kılavuz yazıyorsanız, her sayfanın hangi dosyaları kullandığını açıklamanız gerekebilir.
Adım 2. Hangi düzeyde belgelerin mevcut ve program kodundan ayrılabileceğine karar verin
Program kodunda ne kadar teknik belge yer alırsa, programın farklı sürümlerini açıklamanın yanı sıra güncellemek ve bakımını yapmak o kadar kolay olacaktır. En azından program kodundaki belgeler, işlevlerin, alt rutinlerin, değişkenlerin ve sabitlerin kullanımını içermelidir.
- Kaynak kodunuz uzunsa, bir yardım dosyasına belgeler yazabilir ve bu dosya daha sonra dizine eklenebilir veya belirli anahtar kelimelerle aranabilir. Program mantığı birkaç sayfaya bölünmüşse ve bir web uygulaması gibi destek dosyalarını içeriyorsa, ayrı belge dosyaları yararlıdır.
- Bazı programlama dillerinin (Java, Visual Basic. NET veya C# gibi) kendi kod belgelendirme standartları vardır. Bu gibi durumlarda, kaynak koduna dahil edilmesi gereken standart belgeleri takip edin.
Adım 3. Uygun dokümantasyon aracını seçin
Bazı durumlarda, dokümantasyon aracı kullanılan programlama dili tarafından belirlenir. C++, C#, Visual Basic, Java, PHP ve diğer dillerin kendi dokümantasyon araçları vardır. Ancak, değilse, kullanılan araçlar gerekli belgelere bağlı olacaktır.
- Belge kısa ve basit olduğu sürece, Microsoft Word gibi bir kelime işlemci belge metin dosyaları oluşturmak için uygundur. Çoğu teknik yazar, karmaşık metin içeren uzun belgeler oluşturmak için Adobe FrameMaker gibi özel bir belgeleme aracı seçer.
- Kaynak kodunu belgelemek için yardım dosyaları, RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare veya HelpLogix gibi bir destek dosyası oluşturucu programı ile oluşturulabilir.
Yöntem 2/2: Son Kullanıcılar için Yazılım Belgeleri Yazma
Adım 1. Kılavuzun oluşturulmasının altında yatan iş nedenlerini bilin
Yazılım belgelerinin ana nedeni, kullanıcıların uygulamayı nasıl kullanacaklarını anlamalarına yardımcı olmak olsa da, pazarlama departmanının uygulamayı satmasına yardımcı olmak, şirketin imajını iyileştirmek ve teknik desteği azaltmak gibi belgelerin oluşturulmasının altında yatan başka nedenler de vardır. maliyetler. Bazı durumlarda, düzenlemelere veya diğer yasal gerekliliklere uymak için belgeler gereklidir.
Ancak, dokümantasyon bir arayüzün yerini tutmaz. Bir uygulamanın çalışması için çok fazla belge gerekiyorsa, daha sezgisel olacak şekilde tasarlanmalıdır
Adım 2. Belgelerin hedef kitlesini bilin
Genel olarak, yazılım kullanıcıları, kullandıkları uygulamaların ötesinde sınırlı bilgisayar bilgisine sahiptir. Dokümantasyon ihtiyaçlarını karşılamanın birkaç yolu vardır:
- Yazılım kullanıcısının başlığına dikkat edin. Örneğin, sistem yöneticisi genellikle çeşitli bilgisayar uygulamalarını anlar, sekreter ise yalnızca veri girmek için kullandığı uygulamaları bilir.
- Yazılım kullanıcılarına dikkat edin. Pozisyonları genellikle yapılan görevlerle uyumlu olmakla birlikte, bu pozisyonların iş yerine göre farklı iş yükleri olabilir. Potansiyel kullanıcılarla görüşerek, iş unvanlarına ilişkin değerlendirmenizin doğru olup olmadığını öğrenebilirsiniz.
- Mevcut belgelere dikkat edin. Yazılım işlevselliği belgeleri ve özellikleri, kullanıcıların bunları kullanmak için bilmesi gerekenleri gösterebilir. Ancak, kullanıcıların programın "iç özelliklerini" bilmekle ilgilenmeyebileceğini unutmayın.
- Bir görevi tamamlamak için ne gerektiğini ve tamamlamadan önce ne gerektiğini bilin.
Adım 3. Belgeler için uygun formatı belirleyin
Yazılım dokümantasyonu, referans kitapları ve kılavuzlar olmak üzere 1 veya 2 formatta düzenlenebilir. Bazen iki formatı birleştirmek iyi bir çözümdür.
- Referans biçimleri, düğmeler, sekmeler, alanlar ve iletişim kutuları gibi tüm yazılım özelliklerini ve bunların nasıl çalıştığını açıklamak için kullanılır. Bazı yardım dosyaları, özellikle içeriğe duyarlı olanlar bu biçimde yazılır. Kullanıcı belirli bir ekranda Yardım'a tıkladığında ilgili konuyu alacaktır.
- Manuel format, yazılımla bir şeyin nasıl yapılacağını açıklamak için kullanılır. Kılavuzlar genellikle basılı veya PDF biçimindedir, ancak bazı yardım sayfalarında belirli şeylerin nasıl yapılacağına ilişkin talimatlar da bulunur. (Genellikle, manuel biçimler bağlama duyarlı değildir, ancak bağlama duyarlı konulardan bağlantılı olabilir). El kitapları genellikle bir rehber biçiminde olup, yapılacak işlerin bir açıklaması ve adım adım biçimlendirilmiş bir kılavuzu ile özetlenir.
Adım 4. Belge türüne karar verin
Kullanıcılar için yazılım belgeleri, aşağıdaki formatlardan bir veya daha fazlasında paketlenebilir: basılı kılavuzlar, PDF dosyaları, yardım dosyaları veya çevrimiçi yardım. Her tür belge, ister kılavuz ister öğretici olsun, yazılımın işlevlerini nasıl kullanacağınızı göstermek için tasarlanmıştır. Çevrimiçi belgeler ve yardım sayfaları ayrıca tanıtım videoları, metinler ve statik resimler içerebilir.
Çevrimiçi yardım ve destek dosyaları, kullanıcıların ihtiyaç duydukları bilgileri hızla bulabilmeleri için anahtar kelimeler kullanılarak dizine alınmalı ve aranabilir olmalıdır. Bir yardım dosyası oluşturucu uygulaması otomatik olarak bir dizin oluşturabilse de, yine de sık aranan anahtar sözcükleri kullanarak manuel olarak bir dizin oluşturmanız önerilir
Adım 5. Uygun dokümantasyon aracını seçin
Basılı kılavuzlar veya PDF'ler, dosyanın uzunluğuna ve karmaşıklığına bağlı olarak Word gibi bir kelime işlemci programı veya FrameMaker gibi gelişmiş bir metin düzenleyici ile oluşturulabilir. Yardım dosyaları, RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix veya HelpServer gibi bir yardım dosyası oluşturma programı ile yazılabilir.
İpuçları
- Program dokümantasyonunun metni, okunması kolay olacak şekilde yapılandırılmalıdır. Resmi mümkün olduğunca uygun metne yakın yerleştirin. Belgeleri mantıksal olarak bölümlere ve konulara göre ayırın. Her bölüm veya konu, hem görev hem de program özellikleri olmak üzere belirli bir sorunu tanımlamalıdır. İlgili konular linkler veya referans listeleri ile açıklanabilir.
- Bu makalede açıklanan dokümantasyon araçlarının her biri, dokümantasyonunuz birden fazla ekran görüntüsü gerektiriyorsa, SnagIt gibi bir ekran görüntüsü oluşturma programı ile tamamlanabilir. Diğer belgeler gibi, kullanıcıyı "çekmek" yerine uygulamanın nasıl çalıştığını açıklamaya yardımcı olacak ekran görüntüleri de eklemelisiniz.
- Özellikle son kullanıcılar için yazılım belgeleri yazıyorsanız, stile dikkat etmek çok önemlidir. Kullanıcılara "kullanıcı" yerine "siz" zamiri ile hitap edin.
