Etkili Teknik Dokümantasyon Yazma Stratejileri

Altec Lansing'in İsrail'in Kfar Saba kentindeki Ar-Ge şubesinde kalite güvencesi yaptığım 1999'dan beri şu ya da bu şekilde teknik yazılar yazıyorum. O zamanlar Windows ME ve 2000'de çalışan (gasp) USB ses aygıtları gibi yenilikçi, sesle ilgili aygıtlar piyasaya sürüyorduk. Bunlar sorunluydu ve bunların kurulumu bugünkü kadar kolay değildi.

Dokümanlara ihtiyacımız vardı.

Kullanıcıların geçmesi gereken bazı engellerimiz vardı ve bunların ne olduğunu, uç durumların neler olduğunu ve tüm bunları nasıl teşhis edip düzeltebileceğimizi belgelemenin bir yoluna ihtiyacımız vardı. Güzel bir şekilde paketlenmesi, temiz bir şekilde biçimlendirilmesi ve yardımcı uygulamamızı yükleyen kullanıcılar tarafından erişilebilir olması gerekiyordu. Windows üzerinde standart yardım uygulamaları oluşturmak için kullanılan Robohelp uygulamasını buldum ve kurulumumuza bir yardım dosyası ekledim.

Kalite Güvence sürecimiz sırasında sorunları belirliyor, dikkat çekici olduğunu düşündüğümüz şeyleri belgeliyor ve bunları cihazla birlikte gelen yardım dosyasında düzenliyorduk. O zamanlar 19 yaşındaydım ve bu konularda sıfır deneyimim vardı ve bu son derece naif bir süreçti. Yine de bu, kullanıcılarımız için yapılacak en doğru şeymiş gibi geldi ve yöneticim bana bunu yapmamamı açıkça söylemedi.

24 yıl oldu ve o zamandan bu yana birçok proje için dokümantasyon yapıyorum. Ölçek büyüdü ve bu tür projelere bakış açım büyük ölçüde değişti.

İyi dokümanların nasıl olması gerektiğine dair bazı düşüncelerim var ve eğer ilgileniyorsanız bunları sizinle paylaşmayı çok isterim.

Temel Dokümantasyon Konsepti

Bir belgeleme ürününün başarısı için kritik olduğuna inandığım bir dizi daha somut kuralla başlamak istiyorum.

• Dokümanlar büyük fikirleri tanımlamak için küçük kelimeler kullanmalıdır ; bu nedenle, daha basit terimlerle söylenebilecekleri açıklamak için gösterişli kelimeler veya karmaşık cümleler kullanmayın. Yol boyunca kullanıcıları kaybedeceksiniz ve bu, yazarınızın egosuna değmez.

• Dokümanlar mümkün olduğunda bir hikaye anlatmalıdır ; çünkü bir hikaye anlatan kişisel, ilişkilendirilebilir bir dizi görev, kullanıcınız için soyut bir talimatlar dizisinden daha ilgi çekici ve akılda kalıcı olacaktır.

• Dokümanlar aranabilir olmalıdır - çünkü cidden: bu çok basit bir şey. Dokümanlarınızda içerik bulmak kolay değilse kullanıcılarınız ihtiyaç duydukları şeyi bulamazlar.

• Dokümanlar neredeyse her zaman daha büyük bir stratejinin parçasıdır ve bu özellikle yazılım ürünleri söz konusu olduğunda geçerlidir. Bu, daha geniş bir konu olan geliştirici savunuculuğuna değiniyor, ancak kısacası: Dokümanlarınız video eğitimleri, gerçek kullanım örnekleri ve canlı teknik destek ile desteklenmelidir.

• Dokümanlar test edilmelidir ; çünkü her şeyin doğru olduğundan emin olabilirsiniz, ancak diğer ürünlerde olduğu gibi gerçek kullanıcılar olmadan bunu kesin olarak bilemezsiniz. Test edin ve tekrar test edin.

  
  

Bütünsel dokümanlar iyi tasarlanmış ürünlerdir

Yeni bir programlama dili öğrendiğinizde, o dildeki kavramlar ve fikirler problem çözme hileleri çantanıza akar. Bu sizi daha iyi bir yazılım geliştiricisine dönüştürür ve günün sonunda daha iyi yazılım yaparsınız çünkü daha bilinçli ve yetenekli olursunuz.

Kariyerim karmaşık bir kariyerdi ve birçok yazılım ürünü tasarımı, yazılım geliştirme, teknik destek ve geliştirici savunuculuğunu içeriyordu. Her disiplin, başkalarına nasıl düşündüğümü ve yaklaştığımı etkiledi.

Bir Teknik Yazım projesine yaklaştığımda, kullanıcının ihtiyaç duyacağı şeye dair geniş bir bakış açısına sahip oluyorum. Dokümanlar hakkında düşünmenin doğru yolunun bu olduğunu düşünüyorum: bütünsel olarak. Dokümanlar iyi tanımlanmış bir şey değildir ve iyi dokümanlar oluşturmak için esnek olmanız gerekir.

Bana göre bu, kullanıcılarınızı mümkün olduğu kadar çok açıdan düşünmeniz gerektiği anlamına geliyor. Hiçbir şeyi olduğu gibi kabul edemezsiniz veya markanızı, ürününüzü veya işinizi geri dönüşü zor bir şekilde olumsuz etkileyecek şekilde bazı kullanıcı gruplarını hayal kırıklığına uğratacaksınız.

Dokümanlarınız genellikle kullanıcılarınız için ya başarırsınız ya da kaybedersiniz deneyimidir.

İyi bir iş yaparsanız kullanıcılarınız ürününüzü başarıyla kullanacak ve markanızın şampiyonları haline gelecektir. Bunu yapmazsanız, muhtemelen ürününüzü bir daha asla kullanmayacaklar çünkü dokümanlarınız akıllarında kötü bir tat bıraktı. Başkalarına da bilgi verecekler. İyi pazarlama burada başlar, bu yüzden bunu aklınızda bulundurun.

İyi dokümanlar hazırlamak

İyi dokümanlar oluşturmak, doküman oluşturma sürecinize diğer tüm ürün süreçlerinde olduğu gibi yaklaşmanız gerektiği anlamına gelir.

Gerek:

• Dokümanlarınızı neden oluşturduğunuzu bilin
• Hedef kitlenizin kim olduğunu bilin
• Acı noktalarının ne olduğunu bilin
• Dokümanlarınızı zaman içinde iyileştirin

Bunların her birine daha yakından bakalım.

Dokümanlarınızın nedenini bilmek genellikle yüzeyde yer alan gerçekten basit bir soru ve cevaptır. Dokümanlar oluşturuyorsunuz çünkü bunu yapmazsanız kullanıcılar gözden kaçacak ve ürününüzü kullanamayacaklardır. Daha derin bir düzeyde, kullanım durumunuza özel bir yanıt vardır. Bir geliştirici aracınız mı var? Bu bir cevap seti. Perakende tasarım aracınız mı var? Muhasebe SaaS ürününüz mü var? Otomatik kahve makineniz mi var? Bunların hepsi ayrı cevap kümeleridir.

Dokümanlarınızın biçimi, onu kimin kullanacağına göre tanımlanır. Çevrimiçi mi? Bir uygulamayla birlikte mi geliyor? Basılı mı? Her kullanıcı tabanının başka bir şeye ihtiyacı olacaktır ve onların kim olduklarını en başından itibaren netleştirmelisiniz.

İşiniz, kullanıcılarınızın her biri için neyin zor olduğunu bulmak ve dokümanlarınızı, kullanıcıların özel sorunlarını çözen bilgilendirici içerikle yönlendirmek etrafında oluşturmaktır.

En önemlisi, muhtemelen ilk seferde doğru yapamayacağınızı bilmelisiniz. Bu, ürünleriniz zaman içinde büyüyüp değiştikçe dokümanlarınızın korunması ve güncellenmesi gerektiği anlamına gelir. Umarım bu, yardım etmeye çalıştığınız kullanıcılarla kolay iletişim kurmanıza olanak tanıyan bir çerçeve dahilinde yapılır. Ürününüzü kullanma deneyimlerini daha iyi hale getirmek için kullanıcılarınızla konuşmalı, onların ihtiyaçlarını dinlemeli ve dokümanlarınızı kullanmaya çalışmalısınız.

Dokümanlarınız başarınızın ayrılmaz bir parçasıdır

Dokümanların ne kadar kritik öneme sahip olduğunun altını çizerek özetleyeceğim. Onlar olmadan kullanıcılarınız kendi başlarınadır ve kendi başlarının çaresine bakmak zorundadırlar.

Bu her zaman daha az başarı durumu, ekosisteminizdeki ürününüz hakkında daha kötü görüşler, daha mutsuz geliştiriciler veya kullanıcılar ve markanız veya şirketiniz üzerinde olumsuz bir etki anlamına gelecektir.

Dokümanlar başlı başına ciddi bir alt üründür, bir yatırımdır ve daha geniş ürün stratejinizin bir parçası olmalıdır.