API Ürün Spesifikasyonu Olarak Prototip Kullanmak

SendGrid'de Geliştirici Deneyimi Ürün Yöneticisi olarak, API'mizi içeren fırsatları, özellikleri ve ürünleri belirlemekle görevlendirildim. Üzerinde çalıştığım şeylerden biri, ürün fikirlerimi diğer PM'lere, Mühendislere ve müşterilere daha etkili iletmeyi sağlayacak yöntemler belirlemek.

Monolitik bir Ürün Gereksinimleri Belgesinin (PRD) bunu yapmak için ideal bir yol olmadığını ve bir ürün spesifikasyonu ile aynı bilgileri içeren test edilebilir bir arayüzün güçlü bir alternatif olacağını öğrendim. PRD'lerle ilgili sorun, genellikle çok büyük olmaları ve çoğunlukla metin olmalarıdır. Yerinizi kaybetmek veya gerçekten önemli bir şeyi kaçırmak çok kolaydır.

UX'teki arkadaşlarımız bu sorunu Invision gibi araçlarla çözdüler ve burada sadece arayüzü tanımlayan bir belge veya tel kafes yerine dokunabileceğiniz ve kullanabileceğiniz tıklanabilir bir arayüz sağladılar. API bir arayüz olduğundan, bir belgedeki bir sürü açıklayıcı metin ve JSON yerine, spesifikasyonla gerçek zamanlı etkileşime izin verecek bir araca ihtiyacımız var.

Gereksinimleri Tanımlama

Bir ürün spesifikasyonu olarak bu test edilebilir arayüz neye benzemelidir? Nasıl çalışırdı? Var mı?

Marty Cagan'ın Inspired: How to Build Products Customers Love adlı kitabının 18. Bölümü olan “Ürün Spesifikasyonunu Yeniden Keşfetmek”i okurken, bir ürün spesifikasyonu için Cagan'ın gereksinimlerini karşılayan, kullandığım bir aracı paylaşmak istediğimi fark ettim. onun ürün özellikleri için istek listesi ve benim kendi kişisel spesifikasyon olarak prototip gereksinimleri listem.

Çağan'ın gereksinimleri*:

• Spesifikasyon, tam kullanıcı deneyimini tanımlamalıdır.
• Spesifikasyon, yazılımın davranışını doğru bir şekilde temsil etmelidir.
• Ürünü, tüm paydaşların ihtiyaç duyduklarını alacakları şekilde iletebilmelisiniz.
• Spesifikasyon değişecek
• Belirsizliği ve versiyon iltihabını azaltmak için spesifikasyonun tek bir ana temsili olması gerekir.

Çağan'ın dilek listesi*:

• Prototipi [ile] tamamlamanız gerekecek:
  • İş mantığı
  • Yayın gereksinimleri
  • Platform teslim gereksinimleri
  • Kullanım durumları
• Gerçekten prototipe açıklama ekleyebilmek istiyorum

Spesifikasyon olarak prototip için gereksinimlerim:

• Prototip, spesifikasyon olmalıdır.
• Dokümantasyon prototipe entegre edilmelidir.
• Şirkette ihtiyacı olan herkesin prototipe ve belgelere erişimi olmalıdır.
• Müşteri, kullanıcı testi için prototipin işlevsel kısmına erişebilmelidir.
• Prototip, spesifikasyonun yerini almalı ve bitmiş bir ürünü kablolamadan amaçlanan işlevselliğe yakın çalışmalıdır.
• Prototip üzerinde değişiklik yapmak ve kaydetmek kolay olmalıdır.
• Prototipe erişimi olan herkes tarafından test edilebilecek A/B varyasyonları yapmak kolay olmalıdır.
• Prototipten müşteri belgelerini dışa aktarmak kolay olmalıdır.

StopLight ile tanışın

Kullanmakta olduğum ve yukarıdaki hemen hemen her şeyi karşılayan aracın adı Stoplight.io . Özünde bir API dokümantasyon motoru ve web proxy'sidir. Spesifikasyon motoru olarak sahne arkasında hem Swagger hem de RAML'in en iyisine sahip ve her iki formattan içe veya dışa aktarma yeteneği olan sezgisel bir kullanıcı arayüzü kullanarak API'nizi tanımlamanıza olanak tanır.

StopLight bir belgeleme aracı olduğundan, uç noktalarınız için istekleri, yanıtları, başlıkları ve açıklamaları tanımlayabilirsiniz. Proxy özelliği ile API'nizi arayabilir ve çağrılarınızın spesifikasyonunuza uygun olduğunu doğrulayabilir veya belgelerinizin çoğunun otomatik olarak yazılmasını sağlamak için uç noktalarınızı otomatik olarak keşfedebilirsiniz.

StopLight'ın proxy'si ayrıca kesinlikle şaşırtıcı birkaç başka özelliğe de sahiptir:

• Ürününüz bitmediyse veya isteklerinizi proxy yapmak istemiyorsanız, uç noktalarınıza sahte arama yapma yeteneği.
• Prototipinizi makinenizde test etmek için yerel sunucu.
• Prototipinizi internette test etmek için uzak sunucu.
• Javascript ile yazılmış, prototipinizin uç noktaları çağrılmadan önce ve/veya sonra çalışabilen kodu tanımlamak için yazılmış ara katman yazılımı.

İstek listem, Çağan'ın spesifikasyon gereksinimleri ve istek listesinin kombinasyonunu StopLight'ın sağladığı işlevsellik ile karşılaştırırsanız, StopLight'ın her ihtiyacı ve isteği karşıladığını görebilirsiniz:

• Prototipin ve özelliklerinin yalnızca dahili belgeleri.
• İşlevselliğin kolayca erişilebilen tam bir prototipi.
• Kullanıcı testi ve geri bildirimi için değişken özellikleri değiştirme yeteneğine sahip test edilebilir bir arayüz.
• Aldığınız geri bildirimi göstermek ve doğrulamak için prototipinizin işlevselliğini neredeyse gerçek zamanlı olarak değiştirebilmeniz için prototipinizi belirli bir konuşma için uyarlamanın kolay bir yolu.

StopLight'taki iş akışı basittir ve teknik yetenekleri ne olursa olsun herkes tarafından yapılabilir:

• Yeni bir proje oluşturun.
• Bitiş noktası, parametreleri, isteği ve yanıtı hakkında bilgileri tıklayıp yazarak belirtimi ekleyin.
• Tanımlama ekranında prototipinizle ilgili spesifikasyon bilgilerini ekleyin.
• İsteğe bağlı özellikleriniz varsa, bunları ara yazılımı kullanarak ekleyin.
• Alay etmeyi açın.
• Alaycı sunucunun genel URL'sini kopyalayın/yapıştırın ve bunu geri bildirim için paylaşın.

Bir müşteri ziyaretine gidiyorsanız ve prototipi gerçek zamanlı olarak denemek istiyorsanız, tanımı bilgisayarınıza indirmeniz, ziyaretinizin adını taşıyan yeni bir proje oluşturmanız ve tanımı içe aktarmanız yeterlidir. Artık orijinal prototipinizi değiştirmeden istediğiniz her şeyi değiştirebilirsiniz. Geri döndüğünüzde ve fikirleri birleştirdiğinizde, ilk etapta prototipi oluşturmak kadar değişiklik yapmak da kolaydır.

Geliştirici Deneyimi Ürün Yöneticisi olarak StopLight, yalnızca işimi daha verimli yapmama yardımcı olmakla kalmıyor, aynı zamanda kullanımı son derece basit ve belgeler müşteri doğrulama adımlarından önce başlatıldığından ve güncellendiğinden API'yi belgelemenin teslimat hazırlık adımlarını kolaylaştırıyor. süreç boyunca. StopLight'ın sağladığı başka birçok kullanım durumu ve özellik var, ancak işimi en çok etkileyen bu olabilir.

*Çağan'ın gereksinimleri ve istek listesi, Inspired: How to Build Products Customers Love'dan doğrudan alıntılardır.