Ürün yöneticileri uygun mesajı iletmek için hangi dokümantasyon tarzını kullanmalıdır?

*Dokümantasyon, herhangi bir açık kaynak projesinin en önemli ve en az takdir edilen bileşenlerinden biridir ve hafife alınmamalıdır.

Genel olarak konuşmak gerekirse, çoğu açık kaynak projesi, yazarlarının API ve ürün belgeleri için etkili bir dokümantasyon ortamı oluşturmakla gerçekten ilgilenmedikleri, bunu yapamadıkları veya zamanları olmadığı için yeterli ilgiyi görmemektedir.

Uygulamanız mükemmel olsa da, dokümantasyon yetersizse, tüketiciler kullanımından yararlanamayacaktır.

Ancak, herhangi bir nedenle bunu kullanmaktan başka seçenekleri olmasa bile, bunu başarılı bir şekilde veya sizin istediğiniz şekilde yapamayacaklardır.

Mükemmel dokümantasyonun nasıl üretileceğini anlamak, diğer dokümantasyon projelerini periyodik olarak gözden geçirmek gibi önemli miktarda çalışma gerektirir. Ancak Docsie için çok sayıda dokümantasyon oluşturmuş biri olarak sözüme güvenin - kendinizden başka biri tarafından kullanılacak bir kod oluşturuyorsanız ve özellikle bu kişiler müşterilerinizse, ürününüz iyi belgelenmeli, biçimlendirilmeli ve dinamik olarak sunulmalıdır.

Eğitimler, nasıl yapılırlar, açıklamalar ve referanslar söz konusu olduğunda, aradaki fark nedir?

Birçok kişi yanlışlıkla bu dört ifadenin aynı öğeye atıfta bulunduğuna inanmaktadır. Ancak bu ifadeler çok çeşitli anlamlar ifade etmektedir. Bu farklı belge türleri oldukça önemlidir ve bazı temel farklılıklara sahiptir:

Öğretici Belgeler: Bu tür belgeler, eğitime yönelik bilgi tabanlı belgelerdir.

Nasıl Yapılır Kılavuzları/Kullanıcı Kılavuzları Dokümantasyonu: Kullanıcı kılavuzları belgeleri, belirli bir hedefe ulaşmak için bir dizi adımla belirli sorunların nasıl çözüleceğini ifade eder.

Açıklama Dokümantasyonu: Bunlar, kullanıcının/okuyucunun çeşitli açıklamalar ve arka plan bağlamı yoluyla bir ürünü daha iyi anlamasına yardımcı olmak için tasarlanmış makale türü belgelerdir.

Referans Notları Dokümantasyonu: Bu dokümantasyon, kullanıcıyı çeşitli yeni özellik güncellemeleri ve kullanımları hakkında bilgilendirmek için tasarlanmıştır. Bu tür belgeler, geliştirici belgeleri şeklinde çok 'ham' olabilir, ancak son kullanıcı tarafından kolayca anlaşılabilecek daha kullanıcı dostu sürüm notlarına da çevrilebilirler.

Yüksek kaliteli dokümantasyon üretmek için nedenler

Devam etmeden önce, yetkin dokümantasyon yazımının günümüz toplumunda neden çok önemli ancak yeterince takdir edilmeyen bir ihtiyaç olduğunu anlamak çok önemlidir. Kapsamlı ve iyi yazılmış dokümantasyonun mevcudiyeti, özellikle hemen hemen her eylemin halka açık olduğu ve bu tür faaliyetlerin projenin başarısında çok önemli bir rol oynadığı açık kaynak projelerinde, yaygın benimsemenin sağlanmasında en önemli kriterlerden biridir.

Etkili dokümantasyon yazmak için en önemli nedenlere bir göz atalım.

Müşterileriniz için daha iyi bir ilk katılım deneyimi oluşturmanıza olanak tanır.

Müşterilerinize ürününüzle ilgili yeterli dokümantasyon sağladığınızda, ürününüz konusunda kendilerini daha rahat hissetmelerini ve ürününüze özgü yönergelerle korunmalarını sağlayarak onlara yardımcı olursunuz. Bunun gerçekleşmesi için aşağıdakileri yapmalısınız:

1. Ürün belgelerinizin uygulama içi bağlantılar aracılığıyla veya aranabilir bir belge platformu altında görünür ve kolayca erişilebilir olduğundan emin olun.

2. İyi yazılmış olduklarından ve müşterinin cevabını hızlı ve kolay bir şekilde bulmasına yardımcı olduklarından emin olun

Bir tavsiye de, dokümantasyonunuzu sadece bir kez yazmanızdır; şirketiniz tarafından yeni müşteriler getirildiğinde tekrar tekrar sindirilecektir.

Sonuç olarak, daha az destek talebi gelmektedir.

Belgelerinizi okuyan ve anlayan müşterilerin ürünlerinizi satın alma olasılığı daha yüksektir. Müşteriler herhangi bir şeyi çözemediklerinde, bu oldukça can sıkıcı olabilir ve bunun yerine ürününüzü suçlamaya başlayabilirler.

Bazı müşteriler bir sorunla karşılaştıklarında anında destek personeliyle iletişime geçebilir veya e-posta gönderebilir; ancak belgeler çekici, kolay erişilebilir ve anlaşılırsa, size danışmalarına gerek kalmadan kendi sorunlarını çözebilecekler ve bu da kendilerini daha güçlü hissetmelerini sağlayacaktır.

Kendi ekibinizi desteklemenize yardımcı olur.

Sağlam bir bilgi tabanı kendi ekip üyelerinize yardımcı olmak için de kullanılabilir. Böylece şirket içi ekibiniz yeni özellikler, planlanan yol haritaları, API dokümantasyonu ve herkesi aynı sayfada tutmak için gerekli olan diğer her şey hakkında bilgilendirilmelidir.

Etkili dokümantasyonun nasıl yazılacağına ilişkin adım adım talimatlar

Belgenin içeriğini yazmak ve bu faaliyeti düzenlemek, hangi tonun kullanılacağını belirlemekten ve belgelerinizin anlaşılabilir olmasını nasıl sağlayacağınızdan tamamen farklı iki görevdir. O'Reilly tarafından belirtildiği gibi, mükemmel dokümantasyonun 8 kuralı vardır](https://www.oreilly.com/content/the-eight-rules-of-good-documentation/):

1. Okuyucuyu davet eden belgeler oluşturun.

2. **Projenin tüm alanlarını kapsayan kapsamlı dokümantasyon üretin.

3. Anlaşılması kolay, gözden geçirilebilir materyaller üretin.

4. **Ürünün nasıl kullanılacağını örnek olaylarla gösteren belgeler oluşturun.

5. Gerekli olduğu yerlerde tekrar içeren belgeler yazın.

6. Güncel belgeler yazın

7. Katkıda bulunulması kolay belgeler yazın

8. Keşfedilmesi ve anlaşılması kolay belgeler yazın

Bu unsurlar çoğunlukla içerikle ilgilidir. Bunu takiben, altı adımda bu bilgilerin "nasıl" yapılandırılacağı konusuna gireceğiz:

Ne kaydetmeniz gerektiğine karar verin.

Başlamadan önce ne tür bir dokümantasyon üreteceğinizi düşünmek için biraz zaman ayırın: bir öğretici mi, bir referans belgesi mi, bir kullanım kılavuzu mu yoksa bir açıklama mı?

Ürününüzün niteliğinin, oluşturmaktan sorumlu olacağınız dokümantasyon türü üzerinde doğrudan bir etkisi olacağını unutmayın.

Bir çerçeve oluşturun.

Önce dokümantasyonunuz için bir temel oluşturun. Bu başlangıçta çok küçük bir şey olabilir ve sadece birkaç gruptan oluşabilir, ancak zamanla üzerine inşa ettiğiniz tüm platformun boyutu ve karmaşıklığı artmaya başlayacaktır. Organizasyon yapınızı düzenli olarak gözden geçirmelisiniz.

Unutmayın ki eğitmen sizsiniz ve öğrencilerinizin sınıfınızda nasıl öğrendiklerinden nihai olarak siz sorumlusunuz. Sizin yönlendirmelerinizle yönlendirileceklerdir; bu nedenle, yapıya ne kadar çok zaman harcarsanız, öğrencileriniz çabalarında o kadar başarılı olacaktır.

Her zaman sağlam multimedya tekniklerinden yararlanın.

Videolardan, çizimlerden ve çeşitli stillerden yararlandığınızdan ve bunları doğrudan belgelerinize eklediğinizden emin olun. Docsie bu süreci kolaylaştırmak için bunlardan herhangi birini platformumuza yerleştirmeye izin verir.

Sadece tüketicilerin ifade ettiğiniz bilgileri daha iyi anlamalarına yardımcı olmakla kalmayacak, aynı zamanda dinamik dokümantasyonunuzun bir sonucu olarak daha fazla sayıda yüksek kaliteli potansiyel müşteriye yol açacak harika bir Arama Motoru Optimizasyonu sağlayacaktır.

Aranabilir olduğundan emin olun.

Farklı bilgi bankası platformlarının arama yeteneklerinde farklılıklar vardır - bazıları segmentasyonlara inme yeteneği olmadan yalnızca temel arama sunarken (binlerce dosyanız yoksa teknik olarak iyidir), diğerleri yalnızca belgelerde değil, kullanıcı adlarında da arama yapmanıza olanak tanıyan sorgu seçenekleri sunar.

Ancak, kritik olan bir şey var: hızlı arama yapmanızı sağlayan bir araç kullanmalısınız. Uygulamada bulunan bir arama özelliği, dosyaları aramayı ve uygulamadan çıkmadan önizlemelerini almayı kolaylaştırır.

Docsie, kolayca erişilebilen bilgiler için dinamik olarak aranabilir navigasyona sahip olmanızı sağlar.

Sürekli iyileştirme ve güncelleme çabası

Belgeleri oluşturmak ve kullanmak zordur, çünkü onları oluşturan veya onlardan yararlanan kişiler tarafından çabucak unutulurlar. Belgeler ayrıca yolculukları boyunca bir dizi zorlukla karşılaşırlar.

Zaman geçtikçe, eski belgeler monitör ekranında daha alt bir konumda kalma eğiliminde olduğundan, klasör yapısı bir mezarlık görünümünü alır.

Bu nedenle, eski belgelerinizi gözden geçirdiğinizden ve iyileştirmeler yaptığınızdan emin olun ve iş arkadaşlarınızı da zaman zaman aynı şeyi yapmaya teşvik edin. Docsie, basit ve kolay olan gelişmiş versiyonlama sistemimiz aracılığıyla güncellemeler oluşturmanıza olanak tanır.

Son düşünceler:

Etkili dokümantasyonun nasıl yazılacağı hakkında daha fazla bilgi edinmek ister misiniz? Yazılım dokümantasyonu uzmanları için burada bulunabilecek bir sürü blog ve bilgi var.