İyi Belgeler Nasıl Yazılır (Adım Adım Kılavuz)

Belgelerin nasıl yazılacağını öğrendikten sonra hayatınız çok daha kolay olabilir – kullanıcılarına gerçekten ihtiyaç duydukları şeyi veren iyi, yardımcı belgeler.

Sonuçta, herkes belgeleri okur:

• Pazarlama ekipleri, bir tür pazarlama belgesi olan oyun kitaplarıyla çalışır.
• Destek ve teknik ekipler, kullanıcı kılavuzlarını, kurulum kılavuzlarını, kod notlarını – "temel" teknik belgeleri kullanır.
• Diğerleri standart işletim prosedürlerine, referans materyale, süreç belgelerine, kontrol listelerine – tipik şirket bilgi belgelerine – dayanır.

Müşteriler de, bir çözüm etrafında yollarını öğrenmek veya sorunlarını kendi başlarına hata ayıklamak için müşteriye yönelik belgeleri kullanır (katman 0 desteği).

Tüm bu belgeleri oluşturmanın standart bir yolu olmasa da temel adımlar aynı kalır. Ancak bunları görmeden önce, farklı belge türlerine hızlıca bir göz atalım. Amacına bağlı olarak, bir dokümantasyon parçası dört türden biri olabilir.

Belge türleri

Daniele Procida veya Divio AG, belge türleri hakkındaki konuşmasında belgeleri dört türe ayırır:

• öğrenme odaklı öğreticiler
• hedefe yönelik nasıl yapılır kılavuzları
• anlayış odaklı tartışmalar
• bilgi odaklı referans materyali

Nasıl ifade ettiğinden de anlayacağınız gibi her belgenin farklı bir amacı vardır ve belgelemeden sorumlu olanlar her seferinde bir tane oluşturmak için yola çıktıklarında onu belirlemelidir.

Bunu akılda tutarak, dokümantasyonun nasıl yazılacağına dair kılavuzumuzla başlayalım.

Gerçekten belgelemeniz gerekip gerekmediğini belirleyin

Ürününüz yüzlerce şey yapabilir. Özelleştirmenin daha da fazla yolu olabilir. Binlerce satırlık bir kod tabanınız olabilir. Ayrıca günlük işlerinizde çok fazla bilgi üretiyor olabilirsiniz.

Ama her şeyi belgelemek mümkün değil… ve her şeyin belgelenmesi gerekmiyor.

Bu nedenle, “ belgeleme nasıl yazılır ” sorusunu yanıtlamadan önce, belgelemeniz gerekip gerekmediğini öğrenin.

Belgelemeden önce hedef okuyucularınızı düşünün. Belgeleriniz için hedef okuyucular, son kullanıcıdan yazılım geliştiricinize/geliştiricilerinize veya İK personelinize kadar herkes olabilir. Bilgi işçileri mi? Bu hedef kitlelerin neyle mücadele ettiğini ve onları belgeleyerek daha iyisini yapmaları için gerçekten güçlendirip güçlendiremeyeceğinizi düşünün.

Ayrıca, onu nasıl kullanacaklarını da düşünün. Hedeflenen kullanıcıların belgelerinizle nasıl etkileşimde bulunacağını düşünün.

Müşterileriniz, çözümünüze başlamak için adım adım belgelerinizi takip edecek mi? Bu da belgelerinizi "hedef odaklı" yapar.

Yoksa geliştiricileriniz, bir sonraki sürüm döngünüzde çalışırken ve işbirliği yaparken bunu kullanacak mı? Bu durumda, “anlayış odaklı” belgelere bakıyorsunuz.

Yoksa başvuruları işlerken İK kaynağınız buna başvuracak mı? Burada “bilgi odaklı” dokümantasyonunuz var.

Belgeleriniz onlara gerçekten yardımcı olacak mı?

Bunların dışında, belgeleme çabalarınızın size daha üst düzeyde nasıl yardımcı olacağını da düşünmek isteyebilirsiniz:

• Belgeleriniz sıfır seviye desteğinizi iyileştirecek ve son kullanıcılarınızın sorunlarını kendi başlarına çözmelerine (sapma) olanak sağlayacak mı?
• Ekiplerinizin yaptıkları işte daha iyi olmasını sağlar mı?
• Ekibiniz daha üretken olacak mı?

Ne zaman belgeleyeceğinizi öğrenin

Genel fikir, çok erken (veya geç) başlamamaktır.

Bir sürecin gerçekte nasıl ilerleyeceğinden veya “vizyonunuzu” nasıl gerçekleştireceğinizden emin değilseniz, onu belgelememek ve işler biraz gerçekleşene kadar beklemek en iyisidir.

Örneğin, önümüzdeki çeyrekte önemli bir güncelleme planlıyorsanız ve çalışma yalnızca üst düzey kavramsal aşamadaysa, henüz belge kaynaklarıyla uğraşmayın.

Bu, dokümantasyona “Çevik” yaklaşımdır.

Çoğu zaman, belirli belge türlerini (prosedürler ve süreçler gibi) yapmak için en iyi zaman, onları gerçekten yürüttüğünüz zamandır.

Belgelemenin en iyi yolunu sıfırlayın

İhtiyacınız olan belge türlerine bağlı olarak, hepsini tutmak için bir veya birden fazla yere ihtiyacınız vardır. Bunlar sizin tek hakikat kaynağınız olarak çalışır.

Yelp'in Chastity Blackwell'i, tüm belgeleriniz tek bir yerde güzel bir şekilde saklanmadığında bazı hayal kırıklıklarını paylaşıyor:

Bu hizmetle ilgili her şeyi açıklayan bir belgeniz var ve bu olayı çözmek için ihtiyacınız olan bilginin orada bir yerde olduğundan eminsiniz. "Bunu wiki'de aramayı deneyebilirsin ya da belki Google Dokümanlar deposundadır. Oh, ve ev dizinimde bazı notlar var ve sanırım bir süre önce bununla ilgili bazı e-postalar gördüm."

Doğal olarak, bunun senin başına gelmesini istemezsin. Bu nedenle dokümantasyon araç(lar)ınızı dikkatli seçmelisiniz. Son kullanıcılar için belgeleme yapıyorsanız, Heroic Knowledge Base gibi doldurulması kolay bir bilgi tabanı çözümü kullanmak en iyisidir. Burada bazı alternatifler bulabilirsiniz.

Ekipleriniz için belgeleme yapıyorsanız, WikiPress gibi bir wiki çözümü veya bir dahili bilgi yönetimi çözümü olan Heroic Knowledge Base (evet, tek olarak ikiye katlanır!) ile devam edin. Veya bilgi yönetimi çözümleri için bu seçeneklerden bazılarına göz atın.

Son olarak, kodu belgeliyorsanız, daha özel teknik belgeleme çözümlerinden bazılarını düşünmek isteyebilirsiniz. Heroic Knowledge Base gibi bazı genel amaçlı bilgi tabanı çözümleri, teknik dokümantasyon çözümlerinin yanı sıra işe yarar.

Dokümantasyon sisteminizi seçerken, güncellenmesi kolay bir sistem seçtiğinizden emin olun çünkü kendinizi dokümantasyonunuzu sık sık güncellerken bulabilirsiniz! Belgeleme aracınız ayrıca bazı mükemmel arama işlevleri sunmalıdır.

Ne yazacağına karar ver

Belgeleme pek çok biçimde olabileceğinden, bir biçimi yazmadan önce son haline getirmek çok önemlidir.

Örneğin, HeroThemes'te, müşteriye yönelik belgelerimiz için SSS'ler, kurulum eğitimleri, sorun giderme kılavuzları, ipuçları ve püf noktaları listeleri ve diğerlerinin bir karışımını kullanıyoruz. Müşterilerimizin çoğu da benzer bir kompozisyon kullanıyor.

Ürettiğiniz belgelere ve kimin için ürettiğinize bağlı olarak, belgelerinizin hangi formları alabileceğini bilmeniz gerekir. Jacob Kaplan-Moss, What to write'da bunlardan ayrıntılı olarak bahsediyor. Öğreticilerin, konu kılavuzlarının ve referans materyallerinin çoğu durumda belgelerin büyük bölümünü nasıl oluşturduğunu açıklıyor:

• Öğreticiler: Öğreticiler veya nasıl yapılır, en temel belgeleme biçimidir. Müşteriye yönelik belgelerimiz için öğreticiler, kullanıcılarımızın eklentimizle web sitelerine bir bilgi tabanı eklemek veya onu makalelerle doldurmak için kullandıkları nasıl yapılır kaynaklarımızdır.
• Konu kılavuzları: Konu kılavuzları, öğreticilerden çok daha derine inme ve daha özel konulara hitap etme eğilimindedir. Bunlar bizim için çeviri ve entegrasyon gibi konularda rehberlerimizdir. Bunları gevşek bir şekilde ileri düzey konular olarak sınıflandırıyoruz.
• Referans: Müşteriye yönelik belgeler bağlamında, bu tür, kullanıcılarımızın entegrasyonlarını kurarken yararlı bulabilecekleri ortaklarımızla yaptığımız entegrasyonlar hakkında bilgiler içerir. Veya HeroThemes çözümlerimizden herhangi birini uygularken yararlı bulabilecekleri herhangi bir şeye bağlantılar.

Bir BENİOKU dosyasıyla başlayın (ve üzerine inşa edin)

Tüm bunlar netleştiğinde, artık yazma kısmına hazırsınız. Belgelerin asıl yazma kısmı bir BENİOKU dosyasıyla başlar. Belgeleriniz için kapak sayfası veya anahat olarak düşünün.

(Geliştirici/testçi/iyileştirici) iş arkadaşlarınızın kullanacağı kodunuzun belgeleri üzerinde çalışıyorsanız, BENİOKU dosyanız belirli bir şekilde görünecektir.

Müşteriye yönelik belgeler yazıyorsanız, bunu hedef kitle ve yapılması gereken iş için anlamlı olacak şekilde uyarlamak isteyebilirsiniz. Bununla birlikte, içerik aşağı yukarı aynı kalır. Aşağıda, bir entegrasyonun nasıl çalıştığını açıklayan bir destek makalesinin kendi başına bir kapak sayfasıyla nasıl başladığını görebilirsiniz.

Şimdi, READMe dosyanızı veya belgenizin ana hatlarını alın ve her seferinde bir bölüm doldurun. Belgelerinizi doldurmanıza yardımcı olacak blogumuzdan birkaç kaynak:

• Nihai Bilgi Bankası Makale Şablonu (İnfografik): Müşterilerimizin en başarılı bilgi bankası makalelerini inceledik ve iyi bir bilgi bankası makalesinin nasıl göründüğünü çözdük. Bu tür makaleler, kullanıcıya yönelik belgelerinizin önemli bir bölümünü oluşturur, bu nedenle bunları rekor hızda oluşturmak için bu bilgi grafiğini kullanın.
• Kapsamlı Adım Adım Standart Çalıştırma Prosedürleri (SOP'ler) Nasıl Yazılır: Bu, nasıl yapılır yazımı hakkında hızlı bir nasıl yapılır veya amaçlanan işin nasıl tamamlanacağına dair adım adım talimatlar sunan standart çalıştırma prosedürleridir – çok faydalıdır şirket içi bir wiki veya bilgi tabanı oluştururken.
• Süreç Dokümantasyonu Nedir? Ve Süreçlerinizi Doğru Şekilde Nasıl Belgelersiniz: Şirket içi bilgi belgeleme karmanızın önemli bir parçası olan, süreç belgelerini yazmak için başka bir hızlı nasıl yapılır.
• Sık Sorulan Sorular Nasıl Yazılır ve SSS'lerinize Mükemmel Yanıtları Yazmanın 5 Basit Yolu: Bu iki gönderi, SSS'lerinizi bir saat içinde hazırlamanıza ve bir patron gibi birçok satış öncesi sorguyu saptırmanıza yardımcı olacaktır.

Tamamlandığında, bir inceleme ve test bölümü eklemeyi unutmayın.

İnceleme, dokümantasyon sürecinin önemli bir parçasıdır. Belgelerinizin gerçekten çalıştığından emin olmanıza yardımcı olur. Teknik yazar Tom Johnson, beş adımlı belge inceleme sürecinde, sizin – belge yazarının – yazdığınız adımları izleyerek "ürün çalışmasını" sağladığınız ilk aşamanın kaçırılmaması gerektiğini söylüyor.

Bir güncelleme programı ayarlayın

Belgeler yayınlanır yayınlanmaz bayatlamaya başlar. Yani bir güncelleme programına ihtiyacınız var.

Güncelleme sıklığınız, baktığınız belgelere bağlı olacaktır. Örneğin, kullanıcıya yönelik belgelerinizin yalnızca ürününüzü güncellediğinizde güncellemelere ihtiyacı olacaktır.

Geliştiriciye yönelik belgeler — teknik kod belgeleri — sonsuza kadar devam eder ( satır içi belgeler).

Öte yandan, dahili bilgi/iş belgeleriniz, bir şeyler değiştiğinde, örneğin mevcut proje yönetim aracınızı değiştirdiğinizde veya hatta bazı işleri yapmanın daha optimize bir yolunu keşfettiğinizde güncellemeyi kullanabilir. Kabile bilgisi yakalama ve genel bilgi yakalama, bu tür belgelerde devam eden alıştırmalardan bazılarıdır.

Mantıklı olduğunda, kullanıcıların güncellenmiş bir sürüm gördüklerinde kendilerini kaybolmuş hissetmemeleri için belgelerinize bir değişiklik günlüğü tutun.

Ayrıca, belgelerinizi güncellemenin bir parçası olarak, eski ve yinelenen dosyalardan kurtulun. Belgelerinizde yapılan bir arama asla aynı destek içeriğinin birden çok sürümünü döndürmemelidir. Her konu sadece bir kaynak almalıdır.

Sarmalamak…

Dokümantasyon iş akışınıza uygun dokümantasyonun nasıl yazılacağına dair bu genel kılavuzun ince ayarını yaptıktan sonra, dokümantasyon yazma sürecinizi dokümante edin.

Bunu yapmak, yalnızca belge yazınızı standart hale getirmenize yardımcı olmakla kalmaz, aynı zamanda belgeler her zaman devam ettiği için başkalarının da bunu geliştirmesine olanak tanır.

Size gelince… Şu anda dokümantasyon yazmaya nasıl yaklaşıyorsunuz?