[ad_1]
Yazılım çevrimiçi olduğunda, belgeler de çevrimiçi oldu. Bugün, barındırılan belgeler normdur. Ancak dokümantasyon için formatlar ve teslim yöntemleri değişse de, yazılımı açıklamanın temel amacı değişmedi.
Son yıllarda iyi belgeler yazmak daha da zorlaştı. Yazılım ürünlerini desteklemek için gereken bilgilerin karmaşıklığı önemli ölçüde artmıştır. Aynı zamanda, dokümantasyon için hedef kitle büyüdü ve çeşitlendi.
Yazılımımızın birçok kullanıcısı için belgeler, ürünlerimiz, çalışanlarımız ve markamız hakkında ilk izlenimlerini yaratacaktır. Ve kimse kötü yazılmış belgeleri sevmez. Yetersiz dokümantasyonun bizi bir üründen uzaklaştırdığı ve asla geriye bakmadığımız en az bir deneyimi hepimiz anlatabiliriz.
Bu engel, farklı kültürel, coğrafi ve eğitim geçmişlerinden gelen kullanıcılarınız için daha da yüksek. Herkese hitap eden bir dokümantasyon deneyimi oluşturmak, kapsayıcılık için daha iyidir, teknik olmayan ticari meslektaşlarınız için daha iyidir ve geliştirici deneyimi için daha iyidir. Bugün yazılım belgelerinin okuyucuları herkes olabilir.
İyi bir belgeleme deneyimi sağlamak, herkesin belgelerinizi kolayca sindirebileceği bir ortam yaratmak anlamına gelir. Bu, dokümantasyonunuzun jargon içermemesi ve insanların deney yapmasına izin veren, insanların bir başlangıç noktası olarak kullanabilecekleri örnekler sağlamasına ve gerçek API özellikleriyle birlikte nasıl yapılır bilgilerini içermesine olanak tanıyan “deneyin” yeteneklerini içermesi gerektiği anlamına gelir. Zorlayıcı, eğitici ve kapsayıcı belgeler, sırayla, tüm geçmişlerden teknoloji uzmanlarını davet eden sağlam bir geliştirici deneyimi yaratır.
API belgelerinizi her kullanıcı için iyileştirmeye, ancak özellikle geleneksel olmayan geçmişlere sahip kullanıcılara yardımcı olmaya yönelik beş ipucunu burada bulabilirsiniz.
Tutarlılık için çabalayın
Terminoloji, stil ve organizasyon tutarlılığı, tüm iyi iletişimin ayırt edici özellikleridir. Tüm API programınızın ve dokümantasyon sürecinin temel bir temeli olmalıdır. Belgelerinizde uygun tutarlılığı sağlamak için, yazar ekibiniz genelinde yazma stili ve yaklaşımının aynı olduğundan emin olun.
API gibi bir özellik uygulayarak tüm API program seviyenizde tutarlılığı sağlayın stil kılavuzları grup genelinde tutarlılığı yönetmenize ve korumanıza yardımcı olmak için. Daha iyi bir geliştirici deneyimi oluşturmak ve geçmişleri ne olursa olsun belgelerinizle karşılaşan tüm geliştirici türleri için daha fazla rahatlık sağlamak için belgeleriniz boyunca pratik, öngörülebilir organizasyona ve tutarlı tekliflere odaklanın.
Belgeleriniz için OpenAPI gibi endüstri standartlarını takip etmek, yeni kullanıcıların kendilerini hızlı bir şekilde tanıdık bir kalıba yönlendirmesine ve daha fazla standardizasyon oluşturmasına yardımcı olabilir. Net gezinme seçenekleri ve tutarlı bir stil, hem özellikler hem de dokümanlarınız için keşfedilebilirliği artırır.
Sade bir dil ve arkadaşça bir ton kullanın
Herkes jargondan nefret eder ve bununla yüzleşelim – teknoloji endüstrisinde bir sürü jargon var. Jargon, yalnızca açık iletişimin önüne geçmekle kalmaz, aynı zamanda okuyucuları istenmeyen hissettirebilir. Bu istediğin son şey. Belgelerinizi yazarken, jargon, argo, şakalar, karmaşık kısaltmalar ve benzerlerinin belgelerinizde yeri olmadığını bilerek dili açık ve anlaşılır tutun.
Konu karmaşık olduğunda, o zaman yazınızı daha da basitleştirmelisiniz. Bazı kullanıcıların ürününüze nispeten az resmi eğitimle geliyor olabileceğini unutmamak önemlidir. Yazınız, kendi kendini yetiştirmiş geliştiriciler, ana dili İngilizce olmayanlar ve üniversiteden yeni mezun olmuş geliştiricilerden işi yapmak için çok az zamanı olan deneyimli profesyonellere kadar tüm olası kullanıcılar tarafından erişilebilir olmalıdır. Anlaşılması kolay belgeler sağlayarak hayatlarını kolaylaştırın.
Belgelerinizde kapsayıcı bir ton ve sade bir dil için çabalarken dikkat etmeniz gereken birkaç şey daha var:
- Ayrımcı dile karşı dikkatli olun. Microsoft’un Stil Kılavuzu harika bir kaynak olan önyargısız iletişim hakkında kısa bir bölüm var.
- Kod örneklerinde açık değişken adları ve işlev adları kullanın. Anlamak için özel aşinalık gerektiren terimlerden kaçının.
- Asla varsaymayın. Her belgeye her kavramın ayrıntılı bir tartışmasını eklemeniz gerekmez. Bağlam içinde açıklamak için zamanınız veya alanınız olmadığında, bir tanım veya derinlemesine tartışma ile başka bir kaynağa bağlantı verin. Belgelerinizi okuyanların her şeyi bildiğini varsaymayın.
- Cinsiyetten bağımsız terimler kullanın. Bu bir verilmelidir. İkinci kişiyi (siz, sizin, sizin) kullanmak, hedef kitlenizle bir bağlantı duygusu geliştirmenin harika bir yoludur.
- Resimlere alternatif metin ekleyin. Dokümanlarınızın herkes tarafından erişilebilir olmasını istediğinizi unutmayın. Videodaki tüm grafikler ve altyazılar için alternatif metin ekleyerek bunları ekran okuyucular ve diğer erişilebilirlik araçları için görünür hale getirin.
Teknik olmayanlar için gerekli bilgileri sağlayın
Dokümanlarınıza bakan herkesin geliştirici geçmişi olmaz. Ürün yöneticileri, iş liderleri ve hatta pazarlama ekibindeki meslektaşların bir noktada belgelerinizi kullanmaları gerekebilir.
Anlaşılması kolay, gerçek dünyadan örnekler kullanmak, teknik bilgileri teknik olmayan okuyucular için daha kolay anlaşılır hale getirmeye yardımcı olabilir. Burası “deneyin” veya alay etme yetenekleri (örneğin, stop lambası belgeler) belgelerinizi daha kullanışlı hale getirebilir. Hatta API’nizi potansiyel müşteriler için daha çekici hale getirebilirler.
Örneğin, web mağazası için bir ödeme sistemi uygulamak isteyen bir şirketin ihtiyaçlarını ele alalım. Bir ürün sahibi, gereksinimler hakkında genel bir fikre sahip olacaktır. Müşterilerin ödeme bilgilerini girmek için basit ve güvenli bir yola ihtiyacı vardır. İşletmenin bu ödemeleri işlemek ve izlemek için bir yola ihtiyacı var. Ardından, ödemelerin yerine getirilmesi gereken siparişlere dönüşmesi gerekir.
Ürün sahibi, ödeme sistemi için API belgelerine bakan ilk kişi olabilir. Bir geliştiriciden şirketin ihtiyaçlarını en iyi şekilde karşılayanların derinlemesine bir analizini yapmasını istemeden önce birden fazla API’yi yüksek düzeyde değerlendirmek isteyebilirler. Bu durumda, en iyi belgelere sahip API’nin öne çıkma şansı daha yüksek olacaktır. Unutmayın, belgelerinizi tüketen kişi mutlaka bir geliştirici geçmişinden gelmeyecektir.
Önce tasarım yaklaşımını benimseyin
Stoplight’ta bir tasarım öncelikli yaklaşım yaptığımız her şeye. Bu, arkasındaki insanlar için API’ler oluşturmaya odaklanmak ve API ile etkileşime girebilecek, API’yi oluşturabilecek veya tüketebilecek tüm paydaşları dikkate almak anlamına gelir. Aynı yaklaşım, belgelerinizi tasarlamak için de uygulanabilir. API belgelerinizin, kullanıcıları bulundukları yerde karşılaması ve ihtiyaçlarını karşılaması gerekir. Bir uç noktalar ve yöntemler listesinden daha fazlası olması gerekir.
Potansiyel kullanıcılarınızı farklı hedeflere sahip çeşitli bir grup olarak düşünmek, belgelerinizi yaratıcılığa ilham verecek ve gerçek dünyayı yansıtacak şekilde düzenlemenize yardımcı olabilir. Belgelerinizi yazarken, her kullanım durumu için yazın. Belgelerinizi hazırlarken geleneksel geliştirici, geleneksel olmayan geliştirici, iş ortağı, olası ortaklar ve son tüketici bakış açılarının tümü akılda tutulmalıdır.
Multimedya ile yaratıcı olun
Dokümanlarınızı daha ilgi çekici ve kapsayıcı hale getirmeyi hedefliyorsanız, her zaman uygulamalı uygulama kılavuzlarını sergilemenin yollarını bulmaya çalışın. Yaratıcı olun, farklı şirketlerden ve geliştiricilerden kullanım örneklerini vurgulayın ve gerçek dünya senaryolarına dayalı örnek uygulamalar ve teknik kılavuzlar sağlayın. Belgelerinizi daha çekici hale getirmek ve bilgileri katı metin dışında bir biçimde daha kolay özümseyebilecek kişilere hitap etmek için videolar, grafikler veya gifler gibi multimedyadan yararlanın.
“Kendine nasıl davranılmasını istiyorsan başkalarına da öyle davran” şeklindeki eski söz, belgelerinizi okuyanlar için geçerlidir. Belgelerinizle karşılaşabilecek insan çeşitliliğini ve geçmişleri göz önünde bulundurarak, birinin size bir şeyi nasıl açıklamasını istediğinizi yazın. Geliştirici ve kullanıcı için empati, daha iyi bir uçtan uca geliştirici ve kullanıcı deneyimi için çalışmanın birincil yoludur.
Son bir düşünce olarak, herkes için yazmak beklentileri azaltmak değil, onları genişletmekle ilgilidir. Daha erişilebilir belgeler yazmak, daha fazla kişinin ürününüzü test etmesine ve daha fazlası için geri gelmesine neden olur. Açıkça yazılmış ve geniş ölçüde erişilebilir belgeler, daha üretken geliştiriciler, daha uzun vadeli kullanıcılar, daha derin entegrasyonlar ve daha güçlü marka yakınlığı ile sonuçlanır.
İyi belgelerin nasıl yazılacağı hakkında daha fazla kaynak için, bu en iyi uygulamalar kılavuzuna göz atın.
Pam Goodrich, teknik bir yazar ve dokümantasyon stratejistidir. stop lambası.
–
New Tech Forum, ortaya çıkan kurumsal teknolojiyi benzeri görülmemiş bir derinlikte ve genişlikte keşfetmek ve tartışmak için bir alan sağlar. Seçim, önemli olduğuna inandığımız ve InfoWorld okuyucularının en çok ilgisini çeken teknolojileri seçmemize dayalı olarak özneldir. InfoWorld, yayın için pazarlama teminatı kabul etmez ve katkıda bulunan tüm içeriği düzenleme hakkını saklı tutar. Tüm sorularınızı [email protected] adresine gönderin.
Telif Hakkı © 2022 IDG Communications, Inc.
[ad_2]
Kaynak : https://www.infoworld.com/article/3664096/5-tips-for-writing-better-api-documentation.html#tk.rss_all