Używanie prototypu jako specyfikacji produktu API

Jako Developer Experience Product Manager w SendGrid mam za zadanie identyfikować możliwości, funkcje i produkty, które obejmują nasz interfejs API. Jedną z rzeczy, nad którymi pracuję, jest określenie metod, dzięki którym komunikuję moje pomysły dotyczące produktów innym kierownikom projektu, inżynierom i klientom.

Dowiedziałem się, że monolityczny dokument wymagań produktu (PRD) nie jest idealnym sposobem na zrobienie tego i że testowalny interfejs zawierający te same informacje, co specyfikacja produktu, byłby potężną alternatywą. Problem z PRD polega na tym, że często są one bardzo duże i zawierają głównie tekst. Zbyt łatwo stracić miejsce lub przegapić coś naprawdę ważnego.

Nasi przyjaciele w UX rozwiązali ten problem za pomocą narzędzi takich jak Invision , gdzie zapewniają klikalny interfejs, którego można dotknąć i używać, a nie dokument lub model szkieletowy, który po prostu opisuje interfejs. Ponieważ API jest interfejsem, potrzebujemy narzędzia, które umożliwi interakcję ze specyfikacją w czasie rzeczywistym, a nie garść tekstu opisowego i JSON w dokumencie.

Definiowanie wymagań

Jak powinien wyglądać ten testowalny interfejs jako specyfikacja produktu? Jak by to działało? Czy to istnieje?

Kiedy czytałem rozdział 18, „Reinventing the Product Spec”, Marty Cagan’s Inspired: How to Build Products Customers Love , zdałem sobie sprawę, że chcę podzielić się narzędziem, którego używam, które spełnia wymagania Cagana dotyczące specyfikacji produktu, w większości jego lista życzeń dotycząca specyfikacji produktu i moja osobista lista wymagań dotyczących prototypu jako specyfikacji.

Wymagania Cagana*:

• Specyfikacja musi opisywać pełne wrażenia użytkownika.
• Specyfikacja musi dokładnie odzwierciedlać zachowanie oprogramowania.
• Musisz być w stanie przekazać produkt w taki sposób, aby wszyscy interesariusze otrzymali to, czego potrzebują.
• Specyfikacja ulegnie zmianie
• Musi istnieć pojedyncza główna reprezentacja specyfikacji, aby zmniejszyć niejednoznaczność i zapalenie wersji.

Lista życzeń Cagana*:

• Będziesz musiał uzupełnić prototyp [o]:
  • Logika biznesowa
  • Wymagania dotyczące wydania
  • Wymagania dotyczące dostawy platformy
  • Przypadków użycia
• Naprawdę chcę mieć możliwość dodawania adnotacji do prototypu

Moje wymagania dotyczące prototypu jako specyfikacji:

• Prototyp powinien być zgodny ze specyfikacją.
• Dokumentacja powinna być zintegrowana z prototypem.
• Każdy w firmie, który tego potrzebuje, powinien mieć dostęp do prototypu i dokumentacji.
• Klient powinien mieć dostęp do funkcjonalnej części prototypu do testowania przez użytkownika.
• Prototyp powinien zastąpić specyfikację i działać jak najbliżej zamierzonej funkcjonalności bez okablowania gotowego produktu.
• Tworzenie i rejestrowanie zmian w prototypie powinno być łatwe.
• Tworzenie odmian A/B powinno być łatwe do przetestowania przez każdego, kto ma dostęp do prototypu.
• Eksport dokumentacji klienta z prototypu powinien być łatwy.

Przedstawiamy StopLight

Narzędzie, którego używałem, które spełnia prawie wszystko powyżej, nazywa się Stoplight.io . Jest to w istocie silnik dokumentacji API i serwer proxy. Umożliwia zdefiniowanie interfejsu API za pomocą intuicyjnego interfejsu użytkownika, który ma najlepsze cechy Swaggera i RAML za kulisami jako silnik specyfikacji, a także możliwość importowania lub eksportowania z dowolnego formatu.

Ponieważ StopLight jest narzędziem dokumentacji, możesz zdefiniować żądania, odpowiedzi, nagłówki i opisy dla swoich punktów końcowych. Dzięki funkcji proxy możesz wywołać swój interfejs API i sprawdzić, czy wywołania są zgodne ze specyfikacją lub automatycznie wykryć punkty końcowe, aby większość dokumentacji została napisana automatycznie.

Proxy StopLight ma również kilka innych absolutnie niesamowitych funkcji:

• Możliwość wykonywania próbnych połączeń do punktów końcowych, jeśli produkt nie jest ukończony lub nie chcesz proxy swoich żądań.
• Lokalny serwer do testowania prototypu na Twojej maszynie.
• Zdalny serwer do testowania Twojego prototypu w Internecie.
• Oprogramowanie pośredniczące, napisane w języku JavaScript, służące do definiowania kodu, który może być uruchamiany przed i/lub po wywołaniu punktów końcowych prototypu.

Jeśli porównasz kombinację mojej listy życzeń, wymagań specyfikacji Cagana i jego listy życzeń z funkcjonalnością zapewnianą przez StopLight, zobaczysz, że StopLight spełnia wszystkie potrzeby i pragnienia:

• Tylko wewnętrzna dokumentacja prototypu i jego funkcji.
• Łatwo dostępny pełny prototyp funkcjonalności.
• Testowalny interfejs, który umożliwia przełączanie funkcji zmiennych w celu testowania i opinii użytkowników.
• Łatwy sposób na wersjonowanie prototypu pod kątem konkretnej rozmowy, dzięki czemu możesz modyfikować funkcjonalność prototypu w czasie zbliżonym do rzeczywistego, aby zilustrować i zweryfikować otrzymane opinie.

Przepływ pracy w StopLight jest prosty i może go wykonać każdy , niezależnie od jego umiejętności technicznych:

• Utwórz nowy projekt.
• Dodaj specyfikację, klikając i wpisując informacje o punkcie końcowym, jego parametrach, żądaniu i odpowiedzi.
• Dodaj informacje o specyfikacji swojego prototypu na ekranie Definicja.
• Jeśli masz opcjonalne funkcje, dodaj je za pomocą oprogramowania pośredniczącego.
• Włącz drwiny.
• Skopiuj/wklej publiczny adres URL serwera szyderczego i udostępnij go w celu uzyskania opinii.

Jeśli wybierasz się na wizytę u klienta i chcesz poeksperymentować z prototypem w czasie rzeczywistym, po prostu pobierz definicję na swój komputer, utwórz nowy projekt nazwany tak jak Twoja wizyta i zaimportuj definicję. Teraz możesz zmienić wszystko, co chcesz, bez zmiany oryginalnego prototypu. Kiedy wracasz i łączysz pomysły, wprowadzanie zmian jest równie łatwe, jak tworzenie prototypu w pierwszej kolejności.

Jako kierownik produktu Developer Experience, StopLight nie tylko pomaga mi w bardziej efektywnym wykonywaniu mojej pracy, jest bardzo prosty w użyciu i ułatwia etapy przygotowania dostawy związane z dokumentowaniem interfejsu API, ponieważ dokumentacja została rozpoczęta przed etapami weryfikacji klienta i jest aktualizowana przez cały proces. Istnieje wiele innych przypadków użycia i funkcji, które zapewnia StopLight, ale to może być ten, który najbardziej wpłynął na moją pracę.

*Wymagania i lista życzeń Cagana to bezpośrednie cytaty z Inspired: How to Build Products, Customers Love.