Daha iyi API belgeleri yazmak için 5 ipucu


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.

Telif Hakkı © 2022 IDG Communications, Inc.


Kaynak : https://www.infoworld.com/article/3664096/5-tips-for-writing-better-api-documentation.html#tk.rss_all

Yorum yapın