Mühendis Tarafından Yazılmış Dokümanlarda Yaygın Hatalar ve Bunların Nasıl Düzeltileceği

Son altı ayda, geliştirme ekibimiz "kod olarak dokümanlar" yaklaşımını benimsedi (yolculuğumuz hakkında daha fazla bilgiyi bu adreste bulabilirsiniz). ). Teknik Bölümdeki meslektaşlarımın oluşturduğu belgeleri düzenli olarak inceleyerek, teknik belge yazarken karşılaşılan en yaygın sorunların bir listesini derledim.

Makalede size "kod olarak dokümanlar" yaklaşımının araçlarını kullanarak bu sorunları nasıl çözebileceğinizi göstereceğim.

1. Sayı. “Doküman yazımı bizim sorumluluğumuzda değil”

Belgelerle geçici olarak uğraşmak, tüm geliştirme ekibinin ayağına kurşun sıkmaya benzer. Ekibin kapasitesi eksikse, dokümantasyon bakımını daha teknoloji odaklı ve öngörülebilir hale getirmek zorlayıcı bir nedendir.

Düzeltmek:

• Dokümantasyonun geliştirilmesine "kod olarak dokümanlar" yaklaşımını entegre edin. Bu şekilde, teknik borç biriktirme riski olmadan, kod tabanının yanı sıra belgeleri yinelemeli olarak güncelleyebilirsiniz.
• Teknik belgeleri oluşturabilecek ve tek bir bilgi kaynağı olarak hizmet verebilecek bir alan veya platform geliştirin veya entegre edin.
• Entegre bir geliştirme ortamından (IDE) yararlanın. IDE, eklentileri dahil etmenize ve belge geliştirme için özel komut dosyaları oluşturmanıza olanak tanır. doküman yazmak için mükemmel bir araçtır ancak uygulamalar arasında favorileriniz de olabilir.
• Yazım hatalarına karşı koruma sağlamak için bir yazım denetimi eklentisi yükleyin. Eklentiyi IDE'nize eklemek hızlı ve kolay bir işlemdir.
• Şirket içinde dokümantasyonun geliştirilmesine yönelik standartlaştırılmış bir yaklaşım oluşturmak için, teknik yazım topluluğunun (varsa) görüşlerini dikkate alarak şirketiniz tarafından özel olarak hazırlanmış dahili yönergeleri benimseyin. Bu yönergeleri takip etmek dokümantasyon sürecini kolaylaştıracak ve neyin ve nasıl doğru yazılacağını düşünmede zaman kazandıracaktır.
• Doküman inceleme süresini önemli ölçüde azaltmak veya ortadan kaldırmak için kılavuzlara dayalı kontrolleri otomatikleştirin.
• Mümkün olan her şeyi şablon haline getirin ve dokümantasyon bileşenlerinin standartlaştırılması konusunda ekiple anlaşın.

Teknik dokümantasyonla çalışırken güveninizi artıracak değerli kaynaklar sunacağım. Bu kaynakların, teknik belgeleri etkili bir şekilde kullanmanız için sizi donatacak kadar kapsamlı olduğuna inanıyorum:

• " " geliştirici belgeleri için kapsamlı bir el kitabı görevi görür. Biçimlendirme, noktalama işaretleri, listeleme ve kod blokları ekleme hakkında bilmeniz gereken her şeyi kapsar. Bu kılavuz yeterlidir ve bazılarını ödünç aldığımız dahili yönergelerimizi geliştirmek için değerli bir referans olmuştur. en iyi uygulamalar.
• “ " geliştirici belgeleriyle çalışan, bunları geliştiren, yazan veya sürdüren herkesin mutlaka okuması gereken bir kitaptır. Kitapta teknik yazım alanında birçok tanınmış ve saygın yazar yer almaktadır.

• " " Teknik yazar Anne Gentle tarafından yazılan, OpenStack'teki dokümantasyon kültürünü sergileyen pratik bir kılavuzdur. Yazar, pratik örneklerle dokümantasyonun neden GitHub'da yönetilmesi gerektiğini ve etkili dokümantasyon için teknolojik süreçlerin nasıl uygulanacağını açıklıyor. Kitap ayrıca değerli bilgiler de sunuyor. İster geliştirici ister teknik yazar olun, profesyonel dokümantasyon yazmaya ilişkin bilgiler.

• Ayrıca, şablonları ve biçimlendirme kurallarını içermesi gereken teknik belge yazmaya yönelik dahili yönergelerden de bahsedeceğim. Bu tür kurallar her şirkette mevcuttur. Tipik olarak, teknik yazar-öncü ve geliştirici dokümanları şampiyonları ile işbirliği içinde geliştirilirler ve ekip içindeki dokümantasyon kültürü büyüdükçe gelişirler.

Sorun 2. Belgelerin tek başına yazılması

Tüm dokümantasyonun tek başına geliştirilmesi ve daha sonra incelemeye sunulması, amaçlanan amaca uygun olmayan gereksiz veya ilgisiz dokümantasyon oluşturma riskini taşır.

Düzeltmek:

• Her zaman bir taslakla başlayın ve bunu ekip lideriniz, ürün sahibiniz, teknik yazarınız veya uzman görüşünü sunmak isteyen herhangi bir meslektaşınızla paylaşın.
• Adım adım yazın ve yukarıda belirtilen iş arkadaşlarınıza inceleme için çekme istekleri atayın.
• Geri bildirim toplayın ve üzerinde çalışın.
• Yorumları dikkate alın. Ve inceleme ses tonuna dikkat edin, bazen sert olabilir, ancak bu yalnızca inceleme sürecinin bir özelliğidir.
• Dokümantasyon akışını gözden kaçırmayın. Şirketimizde benimsenen genel akış aşağıda verilmiştir, ancak bu akışın özellikleri şirketin yanı sıra geliştirme ekibine de bağlı olabilir:

3. Sayı. “Anlaması gereken anlayacaktır”

Zaman zaman ekiplerden şunu duyuyorum: "Geliştirme ekibi için yazıyorum", "anlaması gerekenler anlayacaktır", "ekibimizde tarihsel olarak bu şekilde gelişti".

Ancak mesleki jargon ve İngilizce dil, uygunluk ve tutarlılık gerektirir. Bunların aşırı kullanımı çılgın bir mühendisin notlarına benzeyen belgelere yol açabilir.

Dokümantasyon için mümkün olan en basit kelimeleri ve yapıları kullanın. Ana ilkelerden biri kaydırma için yazmaktır. Dokümantasyonun yazılması genellikle çok kapsamlı olduğundan zorlayıcı olabilir, ancak okuyucular nadiren onu baştan sona incelerler. Bunun yerine kaydırma yapma veya anahtar kelime aramayı kullanma eğilimindedirler. Bu nedenle metnin herhangi bir yerden açıldığında kolaylıkla anlaşılabilmesi gerekmektedir.

Düzeltmek:

• Sözlükleri ve güncel normları (veya yalnızca Google'ı kullanarak) kullanarak İngilizce terimleri ve mesleki jargonu kontrol edin. Sözlükte bir kelime varsa dilinizin yazım kurallarına göre yazın.
• Kelime dilde mevcut değilse, orijinal dilinde yazın ve parantez içinde kendi dilinize çevirisini sağlayın.
• Kelimeyi sözlük bölümüne, kısaltmaları ise kısaltmalar ve kısaltmalar listesine ekleyin. Bu, özellikle "özel" kısaltmalar için önemlidir (PO hakkında ne kadar çok bahsedilse veya yazılsa da, anlamı, belgeleri okurken hala sık sorulan sorulardan biridir).
• Tutarlılık – dokümantasyon boyunca seçilen yazı stiline ve kısaltmalara sadık kalın (şirketinizdeki mevcut tüm dokümanlar için daha iyi).
• Belge gezinmesini dikkatli bir şekilde planlayın. Belgenin tamamını okumaya gerek kalmadan ilgili bölümü bulmanın hızlı bir yolu olmalıdır. Bu nedenle içeriğin açık ve öz başlıklarla düşünceli bir şekilde yapılandırılması önemlidir. Basitlik ve kolaylık sağlamak için dahili dokümantasyon şablonları geliştirilmelidir.

Sorun 4. Belgelerin aynı anda birden fazla yerde yazılması

Dokümantasyon için, tek bir gerçek kaynağına sahip olmak, yani gerekli bilgiyi doğruluğundan endişe duymadan bulabileceğiniz tek bir alan çok önemlidir. Teknik dokümantasyonumuz için şirket içi geliştirilen bir platform böyle bir alan görevi görmektedir. Dokümantasyonun farklı alanlarda parçalanmasından kaçınmak, güncel olmayan bilgilerle kimseyi yanıltmayı önlemek açısından çok önemlidir.

Düzeltmek:

• Şirketin bilgi paylaşımı için çeşitli alanlar kullandığı ortaya çıkarsa, teknik belgeleri herhangi bir yerde yayınlamadan önce, başka bir yerde bulunmadığından emin olun.
• Güncel olmayan teknik belgeleri arşivleyin veya silin (sahipliğiniz varsa). Erken silinme konusunda endişeleriniz varsa (örneğin, sayfaya verilen harici bağlantılar nedeniyle), sayfanın güncelliğini yitirdiğini ve daha fazla güncelleme yapılması gereken geçerli dokümanların mevcut dokümantasyon konumunu belirten bir açıklama ekleyin.
• Değerli bilgi veya görüşlerle karşılaşırsanız bunları belgelere ekleyin. Özellikle özel sohbetlerde Slack'te veya başka bir yerde bırakmayın. Paylaşmaya değer bilgi!

kaydeden Anna Goncharova