Yazılım dokümantasyonu yalnızca bir dizi makaleden oluşur. Ama onlar bile seni delirtebilirler. İlk olarak, gerekli talimatları aramak için uzun zaman harcıyorsunuz. O zaman belirsiz metni anlıyorsunuz. Yazıldığı gibi yapıyorsunuz ancak sorun çözülmüyor. Başka bir yazı ararsın, tedirgin olursun... Bir saat sonra her şeyden vazgeçip gidersin. Kötü dokümantasyon bu şekilde çalışır. Bunu bu hale getiren şey nedir ve nasıl düzeltilir - kesimin altını okuyun.
Eski belgelerimizde birçok eksiklik vardı. Yukarıda açıklanan senaryonun müşterilerimizi etkilememesi için neredeyse bir yıldır üzerinde çalışıyoruz. Bakmak, и .
Sorun 1: Net olmayan, kötü yazılmış makaleler
Eğer dokümantasyonu anlamak imkansızsa bunun ne anlamı var? Ancak hiç kimse bilerek anlaşılmaz makaleler yazmaz. Yazarın hedef kitleyi ve amacı düşünmemesi, su dökmesi ve metinde hata olup olmadığını kontrol etmemesi durumunda bunlar meydana gelir.
- seyirci. Bir makale yazmadan önce okuyucunun hazırlık düzeyini düşünmeniz gerekir. Yeni başlayanlara yönelik bir makalede temel adımları atlamamanız ve teknik terimleri açıklama yapmadan bırakmamanız mantıklıdır, ancak yalnızca profesyonellerin ihtiyaç duyduğu nadir bir özellik üzerine bir makalede PHP kelimesinin anlamını açıklamalısınız.
- Gol. Önceden düşünmeniz gereken bir şey daha var. Yazarın net bir hedef belirlemesi, makalenin faydalı etkisini belirlemesi ve okuyucunun makaleyi okuduktan sonra ne yapacağına karar vermesi gerekir. Bu yapılmazsa, açıklama uğruna açıklama elde edersiniz.
- Su ve böcekler. Çok fazla gereksiz bilgi ve bürokrasi var, hatalar ve yazım hataları algıyı etkiliyor. Okuyucu bir gramer uzmanı olmasa bile metindeki dikkatsizlik onu rahatsız edebilir.
Учтите советы выше, и статьи станут понятнее — гарантировано. Чтобы сделать ещё лучше, возьмите на вооружение наши .
Sorun 2. Makaleler tüm soruları yanıtlamıyor
Belgelerin gelişime ayak uyduramaması, gerçek sorulara yanıt vermemesi ve içindeki hataların yıllarca düzeltilmemesi kötü bir durumdur. Bunlar yazarın değil, şirket içindeki süreçlerin organizasyonunun sorunlarıdır.
Dokümantasyon gelişime ayak uyduramıyor
Bu özellik zaten yayında, pazarlama bunu kapsamayı planlıyor ve sonra yeni makalenin veya çevirinin hâlâ belgelerde olmadığı ortaya çıkıyor. Hatta bu yüzden yayınlanmasını ertelemek zorunda kaldık. Herkesten istediğiniz kadar görevleri zamanında teknik yazarlara devretmesini isteyebilirsiniz ancak bu işe yaramayacaktır. Süreç otomatikleşmezse durum tekrarlanacaktır.
YouTrack'te değişiklikler yaptık. Yeni bir özellik hakkında makale yazma görevi, özelliğin test edilmeye başlandığı anda teknik yazara düşer. Daha sonra pazarlama, tanıtıma hazırlanmak için bunu öğrenir. Bildirimler aynı zamanda Mattermost kurumsal mesajlaşma uygulamasına da gelir, bu nedenle geliştiricilerden gelen haberleri kaçırmak imkansızdır.
Dokümantasyon kullanıcı isteklerini yansıtmıyor
Biz böyle çalışmaya alışkınız; bir özellik çıktı, konuştuk. Nasıl açılacağını, kapatılacağını, ince ayarların nasıl yapılacağını anlattık. Peki ya bir müşteri yazılımımızı beklemediğimiz bir şekilde kullanırsa? Yoksa bizim düşünmediğimiz hataları mı var?
Dokümantasyonun mümkün olduğu kadar eksiksiz olduğundan emin olmak için destek taleplerini, tematik forumlardaki soruları ve arama motorlarındaki sorguları analiz etmenizi öneririz. En popüler konular teknik yazarlara aktarılacak ve onların mevcut makaleleri tamamlayabilmeleri veya yenilerini yazabilmeleri sağlanacaktır.
Dokümantasyon iyileştirilmiyor
Bunu hemen mükemmel bir şekilde yapmak zordur; yine de hatalar olacaktır. Müşterilerden geri bildirim almayı umabilirsiniz, ancak her yazım hatasını, yanlışlığı, anlaşılmaz veya asılsız makaleyi bildirmeleri pek olası değildir. Müşterilerin yanı sıra çalışanlar da belgeleri okur, bu da aynı hataları gördükleri anlamına gelir. Bu kullanılabilir! Bir sorunu bildirmenin kolay olacağı koşulları yaratmanız yeterlidir.
Dahili portalda çalışanların dokümantasyona ilişkin yorumlarını, önerilerini ve fikirlerini bıraktıkları bir grubumuz var. Desteğin bir makaleye ihtiyacı var mı, ancak mevcut değil mi? Testi yapan kişi yanlışlığı fark etti mi? İş ortağı, geliştirme yöneticilerine hatalarla ilgili şikayette bulundu mu? Hepsi bu grupta! Teknik yazarlar bazı şeyleri hemen düzeltir, bazılarını YouTrack'e aktarır ve diğerlerine düşünmeleri için biraz zaman tanır. Konunun kaybolmaması için zaman zaman grubun varlığını ve geri bildirimin önemini hatırlatıyoruz.
Sorun 3. Doğru makaleyi bulmak uzun zaman alıyor.
Bulunamayan bir makale, bulunamayan bir makaleden daha iyi değildir. İyi dokümantasyonun sloganı “Araması kolay, bulması kolay” olmalıdır. Bu nasıl başarılır?
Yapıyı düzenleyin ve konu seçme ilkesini belirleyin. Okuyucunun “Bu yazıyı nerede bulabilirim?” diye düşünmemesi için yapı olabildiğince şeffaf olmalı. Özetlemek gerekirse iki yaklaşım vardır: arayüzden ve görevlerden.
- Arayüzden. İçerik panel bölümlerini kopyalıyor. Eski ISPsystem belgelerinde durum buydu.
- Görevlerden. Makale ve bölümlerin başlıkları kullanıcıların görevlerini yansıtır; Başlıklar neredeyse her zaman fiilleri ve “nasıl yapılır” sorusunun yanıtlarını içerir. Artık bu formata geçiyoruz.
Hangi yaklaşımı seçerseniz seçin, konunun kullanıcıların aradıklarıyla alakalı olduğundan ve özellikle kullanıcının sorusuna yanıt verecek şekilde ele alındığından emin olun.
Merkezi bir arama ayarlayın. İdeal bir dünyada, dili yanlış yazdığınızda veya hata yaptığınızda bile aramanın çalışması gerekir. Şu ana kadar Confluence'daki arayışımız bizi bu konuda memnun edemez. Çok sayıda ürününüz varsa ve belgeler genelse, aramayı kullanıcının bulunduğu sayfaya göre uyarlayın. Bizim durumumuzda ana sayfadaki arama tüm ürünler için işe yarar ve zaten belirli bir bölümdeyseniz yalnızca içindeki makaleler için çalışır.
İçerik ve kırıntıları ekleyin. Her sayfada bir menü ve kırıntıların olması iyidir - herhangi bir seviyeye geri dönme yeteneği ile kullanıcının mevcut sayfaya giden yolu. Eski ISPsystem belgelerinde içeriğe ulaşmak için makaleden çıkmanız gerekiyordu. Uygunsuzdu, bu yüzden yenisinde düzelttik.
Bağlantıları ürüne yerleştirin. İnsanlar tekrar tekrar aynı soruyla desteğe geliyorsa, çözümüyle birlikte arayüze bir ipucu eklemek mantıklı olacaktır. Bir kullanıcının ne zaman sorun yaşadığına dair verileriniz veya öngörünüz varsa, onları bir e-posta listesiyle de bilgilendirebilirsiniz. Onlara endişenizi gösterin ve desteğin yükünü üzerinizden alın.
Açılır pencerenin sağ tarafında, ISPmanager'ın etki alanı yönetimi bölümünde DNSSEC kurulumuyla ilgili bir makalenin bağlantısı bulunur
Belgelerde çapraz referansları ayarlama. Birbiriyle ilişkili makaleler “bağlantılı” olmalıdır. Makaleler sıralı ise her metnin sonuna ileri ve geri okları eklediğinizden emin olun.
Büyük olasılıkla, kişi öncelikle sorusunun cevabını size değil, bir arama motoruna arayacaktır. Teknik nedenlerden dolayı oradaki belgelere bağlantı olmaması çok yazık. Bu nedenle arama motoru optimizasyonuna dikkat edin.
Sorun 4. Eski düzen algıyı engelliyor
Kötü metinlerin yanı sıra belgeler tasarım nedeniyle de bozulabilir. İnsanlar iyi yazılmış materyalleri okumaya alışkındır. Bloglar, sosyal ağlar, medya - tüm içerik yalnızca güzel değil, aynı zamanda okunması kolay ve göze hoş geliyor. Dolayısıyla aşağıdaki ekran görüntüsündeki gibi yazıyı gören kişinin acısını rahatlıkla anlayabilirsiniz.
Bu yazıda o kadar çok ekran görüntüsü ve öne çıkan nokta var ki, bunlar yardımcı olmuyor, yalnızca algıyı etkiliyor (resim tıklanabilir)
Dokümantasyondan bir sürü efekt içeren uzun bir okuma yapmamalısınız, ancak temel kuralları dikkate almanız gerekir.
Düzen. Gövde metninin genişliğini, yazı tipini, boyutunu, başlıklarını ve dolgusunu belirleyin. Bir tasarımcıyı işe alın ve işi kabul etmek ya da kendiniz yapmak için Artyom Gorbunov'un "Tipografi ve Düzen" kitabını okuyun. Düzenin yalnızca bir görünümünü sunar, ancak oldukça yeterlidir.
seçim. Metinde neyin vurgulanması gerektiğini belirleyin. Tipik olarak bu, arayüzdeki bir yoldur, düğmeler, kod ekleri, yapılandırma dosyaları, "Lütfen dikkat edin" bloklarıdır. Bu unsurların tahsislerinin ne olacağını belirleyin ve bunları yönetmeliklere kaydedin. Ne kadar az deşarj olursa o kadar iyi olduğunu unutmayın. Birçoğu olduğunda metin gürültülü olur. Tırnak işaretleri bile çok sık kullanıldığında gürültü yaratır.
Ekran görüntüleri. Hangi durumlarda ekran görüntülerinin gerekli olduğu konusunda ekiple anlaşın. Kesinlikle her adımı anlatmaya gerek yok. Çok sayıda ekran görüntüsü dahil. ayrı düğmeler, algıyı engeller, düzeni bozar. Ekran görüntülerindeki vurguların ve imzaların boyutunun yanı sıra formatını belirleyin ve bunları düzenlemelere kaydedin. Resimlerin her zaman yazılanlarla örtüşmesi ve alakalı olması gerektiğini unutmayın. Yine ürün düzenli olarak güncellenirse herkesi takip etmek zor olacaktır.
Metin uzunluğu. Aşırı uzun makalelerden kaçının. Bunları parçalara ayırın ve bu mümkün değilse makalenin başına bağlantı bağlantıları içeren içerik ekleyin. Bir makaleyi görsel olarak kısaltmanın basit bir yolu, dar bir okuyucu çevresinin ihtiyaç duyduğu teknik ayrıntıları spoiler altına gizlemektir.
formatları. Makalelerinizde çeşitli formatları birleştirin: metin, video ve görseller. Bu algıyı geliştirecektir.
Güzel düzen ile sorunları örtbas etmeye çalışmayın. Dürüst olmak gerekirse, biz de "sarmalayıcının" güncel olmayan belgeleri kurtaracağını umduk - işe yaramadı. Metinler o kadar çok görsel gürültü ve gereksiz ayrıntılar içeriyordu ki, düzenlemeler ve yeni tasarım etkisizdi.
Yukarıdakilerin çoğu, dokümantasyon için kullandığınız platform tarafından belirlenecektir. Örneğin Confluence'ımız var. Ben de onunla uğraşmak zorunda kaldım. İlgileniyorsanız web geliştiricimizin hikayesini okuyun: .
İyileştirmeye nereden başlamalı ve nasıl hayatta kalınmalı?
Belgeleriniz ISP sistemininki kadar genişse ve nereden başlayacağınızı bilmiyorsanız, en büyük sorunlardan başlayın. Müşteriler belgeyi anlamıyor; metinleri geliştiriyor, düzenlemeler yapıyor, yazarları eğitiyor. Dokümantasyon güncel değil; dahili süreçlere dikkat edin. En popüler ürünlerle ilgili en popüler makalelerle başlayın: destek isteyin, site analizlerine ve arama motorlarındaki sorgulara bakın.
Hemen söyleyelim - kolay olmayacak. Ve hızlı bir şekilde çalışması da pek mümkün değil. Tabii yeni başlıyorsanız ve hemen doğru şeyi yapmıyorsanız. Kesin olarak bildiğimiz bir şey varsa o da zamanla daha iyi olacağıdır. Ancak süreç hiçbir zaman bitmeyecek :-).
Kaynak: habr.com