Czas czytania: 9 minut
API sprawiają, że świat się kręci. Programiści używają API niemal codziennie – według niektórych szacunków, spędzają oni ponad 10 godzin tygodniowo pracując z API. Obejmuje to nie tylko korzystanie z nich, ale także badania, googlowanie w poszukiwaniu wsparcia, studiowanie recenzji i oczywiście grzebanie w dokumentacji. To, jak jasne, łatwe, użyteczne i obsługiwane jest API, determinuje całe doświadczenie programisty (DX) – emocjonalną reakcję, jaką programiści mają na produkt. W gospodarce opartej na API, doskonałe doświadczenia programistów mają fundamentalne znaczenie. Interfejsy API, które pomagają programistom odnieść sukces i są przyjemne w użyciu, zdobędą mnóstwo użytkowników i wybiją się ponad konkurencję. A zaczyna się to dokładnie w momencie, gdy po raz pierwszy otwierają dokumentację.
Zobacz ten film wprowadzający do technologii API
Dzisiaj porozmawiamy o tym, jak wspierać pozytywne doświadczenia programistów w dokumentacji API. Ale najpierw musimy zrozumieć, co sprawia, że dokumentacja API jest zła.
Czego deweloperzy nienawidzą w dokumentacji API
Społeczność deweloperów jest pełna pasji. Szczególnie pasjonują ją rzeczy, których nie lubią. Jeśli nie podoba im się jakieś API, to w większości przypadków jest to spowodowane zaśmieconymi dokumentami, nawet jeśli produkt jest naprawdę świetny. Oto kilka typowych problemów, jakie mają deweloperzy z dokumentami API.
Nie są napisane prostym, ludzkim językiem. Jest to powszechny problem dla automatycznie generowanych dokumentów lub dokumentów, które są zaniedbywane przez twórców. Chociaż wiele narzędzi do generowania dokumentacji wykonuje świetną pracę przy komentowaniu kodu, nie mogą one zastąpić rzeczywistych wyjaśnień w języku angielskim napisanych przez programistę lub pisarza technicznego.
Ma bardzo mało próbek kodu. Jest to kolejny koniec spektrum, gdzie wyjaśnienia są obfite, ale są minimalne przykłady rzeczywistego kodu.
Jest dostępny tylko dla zarejestrowanych użytkowników. Ten niezbyt zgrabny manewr nie robi nic dla twojego marketingu. To tylko frustruje ludzi, którzy chcą wiedzieć, co robi twój interfejs API, zanim zdecydują, czy chcą go mieć (jak każdy rozsądny człowiek).
Jest zbyt długi/nie można go znaleźć/niedokładny/nie był aktualizowany od lat, itp. Tworzenie dobrych dokumentów jest prawie tak samo ważne jak budowanie dobrego API. Ponieważ źle napisane dokumenty lub takie, których nie można znaleźć po prostu googlując „Product API”, zawodzą cały wysiłek związany z rozwojem. Jeśli jesteś zainteresowany, nakreśliliśmy już specyfikę dokumentacji technicznej w ogóle. Ale dokumenty API zasługują na osobny artykuł. Jak więc napisać świetną dokumentację API?
Zaadoptuj rozwój oparty na specyfikacji
Rozwój oparty na specyfikacji (SDD) jest podobny do rozwoju opartego na testach, w którym piszesz przypadki testowe dla każdej cechy, a następnie piszesz kod, który powinien je przejść. W SDD, tworzysz dokumentację lub przynajmniej jej części równolegle z budową API, często podążając za pewnym formatem opisu API zwanym specyfikacją.
Specyfikacja API jest jak szablon twojej przyszłej dokumentacji, zunifikowany język, który opisuje projekt twojego API, wyjaśnia jak działa i czego można się po nim spodziewać. Istnieje kilka specyfikacji, takich jak RAML (RESTful API Modeling Language), OpenAPI (dawniej Swagger) i API Blueprint, ale istnieje tendencja do łączenia wszystkich specyfikacji pod maską OpenAPI.
Specyfikacje te posiadają wbudowane narzędzia dokumentacyjne, które pozwalają na pisanie i zarządzanie dokumentami. Na przykład API Console automatycznie generuje dokumenty z formatów RAML i OpenAPI i pomaga uruchomić je w istniejącej aplikacji internetowej lub jako samodzielną aplikację.
API Console pozwala zbudować portal internetowy dla twoich dokumentów API ze specyfikacji RAML i OpenAPI
Źródło: Paweł Psztyc
Alternatywa dla tradycyjnych rozwiązań API doc, takich jak WordPress czy Drupal CMS, produkty API spec są open source, tworzone przez społeczność dev dla społeczności dev, mają parsery w różnych językach programowania i stałe wsparcie twórców.
Pisz dla entry level
Jest powód, dla którego dokumentacja techniczna zazwyczaj nie jest pisana przez samych developerów – to zadanie dla technical writerów, ekspertów w tłumaczeniu aspektów technicznych na czytelny format. Ale nawet pisarze techniczni mają tendencję do przeciekania odrobiny żargonu do tekstu.
An API, jak każdy produkt programistyczny, jest tworzony dla konkretnej grupy odbiorców. Ale publiczność dla dokumentacji jest ogromna. Istnieją trzy główne grupy użytkowników dokumentacji:
- developerzy, którzy będą wchodzić w interakcje z dokumentacją
- decydenci, tacy jak CTO i architekci rozwiązań, którzy chcą szybko określić, czy Twój interfejs API będzie dobrze dopasowany
- obserwatorzy, tacy jak dziennikarze, pisarze techniczni, a nawet konkurenci, którzy niekoniecznie będą kiedykolwiek korzystać z Twojego interfejsu API.
A nawet w każdej z tych grup są ludzie o różnych umiejętnościach, rolach i potrzebach, a wszyscy oni powinni mieć pozytywne doświadczenia z dokumentami. Jak dotrzeć do nich wszystkich? Kierując ją do najmniej doświadczonych użytkowników. Jak więc napisać dokumentację dla nowicjusza?
Zacznij od możliwości, a nie od szczegółów technicznych. Przywitaj użytkowników przekonującą opowieścią o tym, jak twoje API może wzbogacić ich produkt lub dziesięciokrotnie ułatwić życie programistów.
Dokumenty API Amazon Alexa zaczynają się od wyjaśnienia, co robi Alexa i jakie korzyści może przynieść klientowi
Pokaż, od czego zacząć. Dokumenty API są notorycznie zbyt przytłaczające i zakładają, że użytkownicy mają duże doświadczenie z interfejsami API. Sekcja dotycząca rozpoczęcia pracy jest obowiązkowa i powinna być napisana z cierpliwością dla potencjalnego użytkownika.
Facebook zapewnia jasne odniesienie dla początkujących i podąża za procesem rozpoczęcia pracy krok po kroku
Stwórz instrukcje dla najczęstszych przypadków użycia. Prawdopodobnie wiesz już, do jakich funkcji ludzie używają twojego API. Stwórz osobne sekcje adresujące je i dołącz tam przykładowe wiadomości.
Używaj konwersacyjnego tonu. Społeczność programistów jest luźna i nieformalna, więc nie docenią suchego, korporacyjnego języka, nawet jeśli brzmi on bardziej „profesjonalnie”. Dobre dokumenty zawsze rozmawiają z ludźmi.
Edukacja na temat zewnętrznych narzędzi. Jeśli twoje API wymaga użycia i zrozumienia produktów i koncepcji innych firm, takich jak OAuth lub npm, dołącz linki do dokumentów lub przewodników instalacji.
Ułatwiaj naukę. Dokumenty API nie są instrukcjami montażu IKEA, ale źródłem nauki. Wzbogać swoją dokumentację o FAQ, tutoriale, blogi, a nawet filmy, gdy jest to możliwe.
Zawrzyj sekcje must-have
W 2019 roku SmartBear, twórca Swaggera, przeprowadził ankietę wśród deweloperów i użytkowników API. Znaleźli, jakie funkcje docs są uważane za najważniejsze w społeczności, dając nam listę sekcji dokumentacji must-have devs chcą pokryć. Przejdziemy przez niektóre z nich.
SmartBear przeprowadził ankietę wśród 3000 praktyków API
Przykłady. Przykłady są zazwyczaj prezentowane jako fragmenty kodu, które są wystarczająco użyteczne, ale można je uczynić jeszcze bardziej praktycznymi. Na przykład, dołączając transkrypcję pól, jak to jest zrobione w dokumentach Medium lub nawet tworząc mock API dla programistów do testowania i używania poprzez wykonywanie prawdziwych połączeń. Mock API mogą być łatwo udostępniane za pośrednictwem adresu URL lub na GitHub, a jeśli zrobione do pewnego poziomu szczegółowości, nawet używane w produkcie końcowym.
Status i błędy. Istnieją standardowe kody statusu i te specyficzne dla twoich API. Dobrym pomysłem jest uwzględnienie wszystkich błędów, które mogą być wywołane przez twój interfejs API. Błędy są często umieszczane na dedykowanej stronie w dokumentach, ale ma sens powielanie niektórych z nich bezpośrednio pod punktem końcowym, gdzie pojawiają się najczęściej.
Uwierzytelnianie. Większość dokumentów API zaczyna się od uwierzytelniania i autoryzacji. Powinien on obejmować informacje o tym, jak uzyskać klucz API i jak uwierzytelnić żądania, w tym możliwe błędy, czasy wygaśnięcia tokena i wyjaśnienie wrażliwości uwierzytelniania (w zasadzie przypominając, że klucze nie mogą być współdzielone i gdzie mogą być używane).
ŻądaniaHTTP. Dostarczanie żądań sieciowych w HTTP to absolutne minimum dla dokumentacji. Zazwyczaj zakłada się, że programiści będą wiedzieli jak wysyłać żądania HTTP w wybranym przez siebie języku, ale czasami twórcy API dołączają żądania w różnych językach. Można to zrobić automatycznie za pomocą narzędzi specyfikacji API i narzędzi zarządzania API, takich jak Postman.
Użyj standardowego układu
Jeśli używasz generatora dokumentacji, układ jest już ustalony za ciebie. Większość dokumentów API wygląda i czuje się tak samo. Jeśli używałeś kilku z nich, wiesz jak podchodzić do nowych dokumentów. Mimo to, zorganizowanie dużej ilości danych, sprawienie, że są one łatwe do znalezienia i nawigacji jest skomplikowanym zadaniem. Oto kilka cech najbardziej funkcjonalnego układu.
Układ dynamiczny. Możesz rozpoznać przestarzałe API po jego statycznej dokumentacji. Pojedyncza strona lub nawet dokument PDF nie wystarczą w 2020 roku. Dynamiczne dokumenty są łatwe do przeglądania, aktualizacji i zakładek.
Klejąca się zawartość. Nie, pasek nawigacyjny nie rozprasza, ani nie kradnie cennego miejsca na ekranie. Zawsze trzymaj zawartość w zasięgu wzroku.
Układ trójkolumnowy. Niezbyt często używany, ten układ pozwala na posiadanie kolejnej kolumny po prawej stronie dla przykładów kodu. Oczywiście, ma to sens tylko wtedy, gdy masz dużo tekstu i chcesz wyróżnić kod, aby użytkownicy nie musieli przewijać do przodu i do tyłu lub przełączać się między zakładkami.
Dokumenty API HubSpot używają układu trójkolumnowego
Użyj kontrastowych kolorów dla składni. Programiści spędzają dużo czasu patrząc na przykłady kodu, więc spraw, aby były one czytelne i oddziel różne elementy kolorem.
Ten przykład z dokumentacji API Graph Facebooka pokazuje również, jak można użyć różnych zakładek do wyboru pomiędzy SDK
Zapisany stan przewijania. Jest to mały szczegół, który doceni każdy programista. Możesz również użyć linków zakotwiczenia, aby określić różne sekcje strony na wypadek, gdyby skopiowali adres URL.
Zachęcaj do wyrażania opinii. Twoje dokumenty są twoim głównym narzędziem marketingowym – jeśli ludzie je pokochają, będą używać twojego API zamiast API konkurencji i napędzać społeczność wokół niego. Zwykła wiadomość „Czy ta strona była pomocna?” da ci znać, jak dobrze odpowiadasz na pytania deweloperów, a formularz opinii będzie często używany tak długo, jak długo będziesz go dostarczał.
Nie porzucaj swoich dokumentów
Nieaktualne dokumenty to największy pet peeve użytkowników API. Jest to również jeden z najczęstszych błędów. Programiści często piszą o aktualizacjach kilka dni po ich wprowadzeniu, czasem ograniczając się do kilku zdań. Dzieje się tak, ponieważ nie ma ustalonego procesu aktualizacji docsów i nikt nie jest za to odpowiedzialny. Oto jak zapewnić regularne i przydatne aktualizacje dokumentów.
Przygotuj dokumenty przed aktualizacjami. Uczyń z tego dodatkowy krok w swoim planie uruchamiania, nie wprowadzaj ich zanim nie będziesz miał dobrze napisanych, szczegółowych i zredagowanych paragrafów wprowadzających aktualizacje.
Regularnie usuwaj przestarzałe dane. Dokumenty muszą być często przeglądane, przynajmniej raz na kilka miesięcy. Funkcje opinii użytkowników pozwolą ci wcześniej wychwycić niespójności i zawsze powinien być członek zespołu odpowiedzialny za ich przeglądanie i reagowanie na aktualizacje.
Używaj analityki do ulepszania dokumentów. Standardowa analityka API powie Ci, które punkty końcowe są używane częściej, więc możesz skupić się na pewnych częściach dokumentacji i dostarczyć więcej przydatnych informacji lub stworzyć dedykowane tutoriale. Monitoruj przypadki użycia twoich API, ponieważ to pozwoli ci poszerzyć propozycję wartości i zaktualizować dokumenty o więcej możliwości.
Wspaniałe przykłady dokumentacji API
Są tony dobrych dokumentów do zbadania i nauki. Oprócz przykładów, którymi dzieliliśmy się w całym artykule, oto kilka kolejnych, którymi możesz się cieszyć i na które możesz zwrócić uwagę.
Dokumentacja API Medium
Dokumenty API Medium niekoniecznie przestrzegają wszystkich zasad, które dziś wymieniliśmy, ale są świetne dla ograniczonej funkcjonalności tego API – zamieszczania i wyszukiwania publikacji na Medium. Są udostępniane na GitHubie, mają naprawdę krótką, ale przejrzystą treść z mnóstwem przykładów, a każdy z nich kończy się transkrypcją wszystkich parametrów wymienionych w kodzie, łącznie z możliwymi błędami. Jest to niezwykle proste, ale niezawodne – wszystkie sugestie można zgłaszać bezpośrednio na GitHubie, a docs są regularnie aktualizowane.
Dokumentacja API Mailchimp
Mailchimp zdaje sobie sprawę, że większość jego odbiorców to marketingowcy i używa języka, który pozwala nawet osobom nietechnicznym zrozumieć, jak pracować z jego API. Na pierwszy rzut oka każda sekcja ma taką samą strukturę:
- co robi punkt końcowy i co przewodnik pozwoli użytkownikom zrobić
- co będzie potrzebne – wszelkie dostępy lub konta, które użytkownik musi najpierw uzyskać
- jak wygląda każda funkcja z opisem tekstowym, przykładem kodu w kilku językach i czasami zrzutami ekranu interfejsu.
Dla każdego fragmentu kodu jest nawet przycisk kopiowania – szczegół, który z pewnością docenią nietechnicy.
Dokumentacja API Twilio
Twilio ma bardzo dobre dokumenty API. Chociaż dokumenty to tylko wierzchołek góry lodowej całej pomocy, którą Twilio się dzieli – są SDK w kilku językach i przykładowe aplikacje dla iOS, Android i www. Przede wszystkim trzymają się one trójkolumnowej logiki z kodem bezpośrednio po prawej stronie przewodnika. Najprostsze działania są wyjaśnione z detalami i mnóstwem linków do dodatkowych informacji i zrzutów ekranu. Zachęcamy również do wyrażania opinii poprzez przycisk „Oceń tę stronę” i linki do zespołu pomocy technicznej i tagu na StackOverflow.
Dokumentacja API Spotify
Mimo, że dokumenty API Spotify są bardzo typowe, mają wiele dodatkowych informacji w swojej platformie Spotify for Developers. Są tam dema podstawowych funkcji, przykładowe aplikacje, przykłady na żywo zbudowane przy użyciu interfejsów API Spotify i widżetów, wrappery dla różnych języków programowania i oczywiście konsola. Konsola jest w zasadzie interaktywną dokumentacją, w której możesz wypełnić swoje (lub przykładowe) dane i zbadać punkty końcowe na żywo. Potężne produkty wraz z silną bazą wiedzy sprawiają, że Spotify jest wiarygodnym partnerem, z którym deweloperzy lubią pracować.
Treat docs with care
Dokumentacja jest jedynym punktem kontaktu, jaki będziesz miał z większością swoich odbiorców, więc musisz nauczyć się jasno komunikować za jej pomocą. Najlepszą wskazówką jest uczynienie z niej zadania dla kogoś. Często jest to pisarz techniczny, który wie, jak przemawiać do odbiorców o różnych umiejętnościach, który potrafi przełożyć słowa programistów na punkty, które można wykorzystać w praktyce, który monitoruje terminowe utrzymanie i aktualizację dokumentacji. Ale zarządzanie świetną dokumentacją jest możliwe nawet bez eksperta w zespole. Narzędzia do zarządzania API, takie jak Swagger UI, Spotlight, Apiary i narzędzia do specyfikacji docs mają szeroką funkcjonalność, aby pomóc Ci stworzyć dokumenty, które pokochają programiści.