İyi Bir Dokümantasyon Nasıl Yazılır (üvey-Demon-Adım Guid)

Kullanıcılara gerçekten ihtiyaç duydukları şeyleri veren belgelerin iyi ve kullanışlı belgeleri nasıl yazacağınızı bildikten sonra hayatınız çok daha kolay olabilir. Ancak herkes belgeyi okur:
Pazarlama ekibi bir rehber kitap – bir tür pazarlama belgesi ile çalışır.
Destek ve teknik ekipler kullanıcı yönergelerini, kurulum kılavuzlarını, kod notlarını kullanır – teknik belgeler “çekirdek”.
Diğerleri standart işletim prosedürlerine, referans materyallerine, süreç belgelerine, kontrol listesine – tipik şirket bilgi belgelerine bağlıdır.
Müşteriler ayrıca, çözümleri öğrenmek veya kendi sorunlarını hata ayıklamak için müşterilerin karşılaştığı belgeleri kullanır (Destek Seviyesi 0).
Tüm bu belgeleri yapmanın standart bir yolu olmasa da, temel adımlar aynı kalır. Ama görmeden önce, farklı bir belgeye bir göz atalım. Amacına dayanarak, dokümantasyon çalışmaları dört türden biri olabilir. Dokümantasyon türleri üzerine dokümantasyon türleri, Daniele Prodida veya Divio AG belgeleri dört türe kategorize eder:
Öğrenme yönelimli öğretici
Hedefe yönelik yol rehberi
Yönlendirilmiş Tartışmayı Anlamak
Bilgi odaklı referans materyali
Söylediği şekilde anlayabildiğiniz gibi, belgelerin her bir bölümünün farklı bir amacı vardır ve belgelerden sorumlu olanların her yapmaya başladığında bunu ayarlamaları gerekir. Bunu hatırlayarak, belgelerin nasıl yazılacağına dair rehberliğimizle başlayalım.
Bunu gerçekten belgelemeniz gerekip gerekmediğini belirleyin, ürününüz yüzlerce şey yapabilir. Belki onu ayarlamanın daha fazla yolu vardır. Binlerce satırın temeline sahip olabilirsiniz. Ayrıca günlük çalışmalarınızda çok fazla bilgi üretebilirsiniz. Ancak her şeyi belgelemek mümkün değildir … ve her şeyin belgelenmesi gerekmez. “Dokümantasyon nasıl yazılır” sorusunu cevaplamadan önce, tamamen belgelemeniz gerekip gerekmediğini bilin. Belgelenmeden önce hedef okuyucularınızı düşünün. Belgeleriniz için hedef okuyucular, son kullanıcılardan yazılım geliştiricinize veya İK’na kadar herkes olabilir. Bilgi çalışanları mı? Hedef kitlenin ne için savaştığını düşünün … ve eğer belgelenerek daha iyisini yapmaları için onları gerçekten güçlendirebiliyorsanız. Ayrıca, nasıl kullanacaklarını düşünün. Amaçlanan kullanıcının belgelerinizle nasıl etkileşime gireceğini düşünün. Müşterileriniz çözümünüzü başlatmak için belgelerinizi adım adım takip edecek mi? Dokümantasyonunuzu “yönelimli” yapan şey. Yoksa geliştiriciniz bunu bir sonraki sürüm döngüsünde çalışıp işbirliği yaparken kullanacak mı? Bu durumda, “yönelimli anlama” belgesine bakıyorsunuz. Yoksa İK kaynaklarınız uygulamayı işlerken ona başvuracak mı? Burada “bilgi odaklı” bir belgeniz var.
Ve belgeleriniz onlara gerçekten yardımcı olacak mı? Bunun yanı sıra, dokümantasyon çabalarınızın size daha yüksek bir seviyede nasıl yardımcı olacağını düşünmek isteyebilirsiniz:
Dokümantasyonunuz sıfır seviyeli desteğinizi artıracak ve son kullanıcınızın kendi sorunlarını (sapma) çözmesine izin verecek mi? Takımınızı yaptıkları işte daha iyi hale getirecek mi?
Ekibiniz daha üretken olacak mı?
Genel fikrin ne zaman belgeleneceğini öğrenin, çok erken (veya geç) başlamayacak. Bir sürecin gerçekte nasıl çalışacağından veya “vizyonunuzu” nasıl çalıştıracağınızdan emin olmadığınız sürece, bunu belgelememelisiniz ve her şey gerçekleşene kadar beklemelisiniz.
Örneğin, önümüzdeki çeyrekte önemli bir güncelleme planlıyorsanız ve yalnızca yüksek seviyeli bir kavramsal aşamada çalışıyorsanız, önce dokümantasyon kaynaklarını kullanmayın. Bu, belgeler için “çevik” yaklaşımdır.
Görüntü kaynakları genellikle, belirli dokümantasyon türlerini (prosedürler ve süreçler gibi) yapmak için en iyi zaman, gerçekten çalıştırdığınız zamandır. İhtiyacınız olan dokümantasyon türüne bağlı olarak belgelemenin en iyi yolunu öğrenin, her şeyi saklamak için bir veya birkaç yere ihtiyacınız var. Bu, gerçeğinizin tek kaynağı olarak işlev görür.
Yelp’den Chastity Blackwell, tüm belgeleriniz tek bir yerde iyi saklanmadığında birkaç hayal kırıklığı paylaşıyor: Hizmet hakkında her şeyi açıklayan bir belgeniz var ve bu olayı tamamlamanız gereken bilgilerin orada olduğundan eminsiniz. “Wiki’de veya belki de Repo Google belgelerinde aramaya çalışabilirsiniz. Oh, ve ev dizinimde birkaç not var ve sanırım bir süre önce bununla ilgili bazı e -postalar gördüm. ” Tabii ki, bunun başına gelmesini istemezsiniz. Bu yüzden bir dokümantasyon aracı seçmelisiniz. Son kullanıcıyı belgelerseniz, kahramanca bilgi tabanı gibi kolayca doldurulmuş bir bilgi tabanı çözümü kullanmalısınız. Burada birkaç alternatif bulabilirsiniz. Ekibinize belgelenirseniz, Wikipress veya Dahili Bilgi Yönetimi Çözümleri gibi Wiki Çözümlerini Kahraman Bilgi Üssü’nü kullanın (evet, çift olarak çalışır!). Veya bilgi yönetimi çözümleri için bu seçeneklerden bazılarına bakın. Son olarak, kodu belgelerseniz, bazı daha özel teknik dokümantasyon çözümlerini göz önünde bulundurmak isteyebilirsiniz. Kahramanlık Bilgi Üssü gibi bazı bilgi tabanı çözümleri teknik dokümantasyon çözümleriyle birlikte iyi çalışır. Dokümantasyon sisteminizi seçtiğinizde, belgelerinizi genellikle güncelleyebileceğiniz için kolayca güncellendiğinden emin olun! Dokümantasyon aracınız ayrıca birkaç mükemmel arama işlevi sunmalıdır.