Olvasási idő: 9 perc
APIs make the world go round. A fejlesztők szinte minden nap használnak API-kat – egyes becslések szerint hetente több mint 10 órát töltenek API-kkal. Ez nemcsak a használatukra terjed ki, hanem a kutatásra, a guglizásra, a támogatás keresésére, a vélemények tanulmányozására és természetesen a dokumentációban való turkálásra is. Az, hogy az API mennyire egyértelmű, egyszerű, hasznos és támogatott, meghatározza a teljes fejlesztői élményt (DX) – a fejlesztők érzelmi reakcióját a termékre. Az API-gazdaságban a nagyszerű fejlesztői élmény alapvető fontosságú. Azok az API-k, amelyek segítik a fejlesztők sikerét, és amelyeket öröm használni, rengeteg felhasználót szereznek, és a konkurencia fölé emelkednek. És ez pontosan abban a pillanatban kezdődik, amikor először megnyitják a dokumentációt.
Nézze meg ezt a videót az API-technológia bemutatásáért
A mai napon arról fogunk beszélni, hogyan lehet elősegíteni a pozitív fejlesztői élményt az API-dokumentációban. De előbb meg kell értenünk, mitől lesz rossz az API-dokumentáció.
Mit utálnak a fejlesztők az API-dokumentációban
A fejlesztői közösség szenvedélyes. Kifejezetten szenvedélyes azokkal a dolgokkal kapcsolatban, amelyeket nem szeretnek. Ha nem szeretnek egy API-t, az legtöbbször az ócska dokumentáció miatt van, még akkor is, ha a termék valójában nagyszerű. Íme néhány gyakori probléma, amit a fejlesztők az API dokumentációval kapcsolatban tapasztalnak.
Nem egyszerű emberi nyelven íródott. Ez gyakori probléma az automatikusan generált vagy a készítők által elhanyagolt dokumentációk esetében. Bár sok dokumentációgeneráló eszköz nagyszerű munkát végez a kód kommentálásában, ezek nem helyettesíthetik a fejlesztő vagy műszaki író által írt tényleges angol nyelvű magyarázatokat.
Nagyon kevés kódmintát tartalmaz. Ez a spektrum másik vége, ahol a magyarázatok bőségesek, de a tényleges kódból minimális példa van.
Ez csak regisztrált felhasználók számára érhető el. Ez a nem túl ügyes manőver nem tesz semmit a marketing érdekében. Csak frusztrálja azokat az embereket, akik tudni akarják, hogy mit csinál az API-ja, mielőtt eldöntenék, hogy kell-e nekik (ahogy minden épeszű ember tenné).
Túl hosszú/nem lehet megtalálni/helytelen/évek óta nem frissítették stb. A jó dokumentáció létrehozása majdnem olyan fontos, mint egy jó API létrehozása. Mert a rosszul megírt dokumentációk, vagy azok, amelyeket nem lehet megtalálni, ha egyszerűen rákeresünk a “Product API”-ra, kudarcot vallanak az egész fejlesztési erőfeszítésben. Ha érdekel, már felvázoltuk a műszaki dokumentáció sajátosságait általában. De az API-dokumentumok megérdemelnek egy külön cikket. Hogyan írhatsz tehát nagyszerű API-dokumentumokat?
Vállalj specifikációvezérelt fejlesztést
A specifikációvezérelt fejlesztés (SDD) hasonló a tesztvezérelt fejlesztéshez, amelyben minden egyes funkcióhoz teszteseteket írsz, majd olyan kódot írsz, amelynek át kell mennie ezeken. Az SDD-ben az API építésével párhuzamosan készít dokumentációt vagy legalábbis annak egyes részeit, gyakran egy bizonyos API leírási formátumot, az úgynevezett specifikációt követve.
Az API specifikáció olyan, mint a jövőbeli dokumentáció sablonja, az az egységes nyelv, amely leírja az API tervezését, elmagyarázza, hogyan működik, és mit várhatunk tőle. Létezik néhány specifikáció, például a RAML (RESTful API Modeling Language), az OpenAPI (korábban Swagger) és az API Blueprint, de van egy olyan trend, amely az összes specifikációt az OpenAPI motorháztetője alatt egyesíti.
Ezek a specifikációk előre beépített dokumentációs eszközökkel rendelkeznek, amelyek lehetővé teszik a dokumentáció megírását és kezelését. Az API Console például automatikusan létrehozza a RAML és OpenAPI formátumú dokumentációkat, és segít a meglévő webes alkalmazáson vagy önálló alkalmazásként futtatni.
Az API Console segítségével webes portált építhet az API dokumentációi számára a RAML és OpenAPI specifikációkból
Forrás:
A hagyományos API-dokumentációs megoldások, például a WordPress vagy a Drupal CMS-ek alternatívájaként az API-specifikációs termékek nyílt forráskódúak, a fejlesztői közösség készítette őket a fejlesztői közösség számára, különböző programozási nyelveken vannak parsereik, és folyamatos támogatást nyújtanak a készítőknek.
A belépőszintűeknek írni
A technikai dokumentációt általában nem maguk a fejlesztők írják – ez a technikai írók feladata, akik a technikai szempontok olvasható formátumba való lefordításának szakértői. De még a műszaki írók is hajlamosak arra, hogy egy kis szakzsargon szivárogjon a szövegbe.
Az API, mint minden szoftvertermék, egy meghatározott célközönség számára készül. A dokumentáció közönsége azonban hatalmas. A dokumentáció felhasználóinak három fő csoportja van:
- fejlesztők, akik szorosan együttműködnek a dokumentációval
- döntéshozók, mint például a technológiai igazgató és a megoldás-architektek, akik gyorsan meg akarják állapítani, hogy az API megfelelő lesz-e
- megfigyelők, mint például újságírók, műszaki írók, és még a versenytársak is, akik nem feltétlenül fogják használni az API-t soha.
És még e csoportok mindegyikén belül is vannak különböző készségekkel, szerepekkel és igényekkel rendelkező emberek, és mindegyiküknek pozitív élményt kell szereznie a dokumentációval kapcsolatban. Hogyan célozza meg mindannyiukat? Úgy, hogy a legkevésbé tapasztalt felhasználókat célozza meg. Szóval, hogyan írjon dokumentumokat egy kezdő felhasználó számára?
Kezd inkább a lehetőségekkel, mint a technikai részletekkel. Köszöntse a felhasználókat egy meggyőző történettel, amely elmondja, hogyan gazdagíthatja az API-ja a terméküket, vagy hogyan teheti tízszer könnyebbé a fejlesztők életét.
Amazon Alexa API dokumentációi azzal kezdődnek, hogy elmagyarázza, mit csinál az Alexa, és milyen előnyökkel járhat az ügyfél számára
Mutassa meg, hol kezdje. Az API-dokumentumok arról híresek, hogy túlságosan túlterheltek, és feltételezik, hogy a felhasználóknak hatalmas tapasztalata van az API-kkal kapcsolatban. A Kezdő rész kötelező, és türelemmel kell megírni a potenciális felhasználó számára.
A Facebook egyértelmű hivatkozást nyújt a kezdők számára, és lépésről lépésre követi a kezdeti folyamatot
A leggyakoribb felhasználási esetekre vonatkozó utasításokat. Valószínűleg már tudja, hogy az emberek milyen funkciókra használják az API-ját. Hozzon létre külön, ezeket megszólító szakaszokat, és tartalmazzon ott mintaüzeneteket.
Beszélgetős hangnemet használjon. A fejlesztői közösség laza és kötetlen, ezért nem fogják értékelni a száraz vállalati nyelvet, még akkor sem, ha az “profibbnak” hangzik. A jó dokumentációk mindig emberekhez szólnak.
Tájékoztasson a külső eszközökről. Ha az API-ja megköveteli harmadik féltől származó termékek és fogalmak, például az OAuth vagy az npm használatát és megértését, tegyen közzé hivatkozásokat a dokumentációkra vagy telepítési útmutatókra.
Megkönnyíti a tanulást. Az API-dokumentumok nem IKEA összeszerelési útmutató,;a tanulási forrás. Gazdagítsa dokumentációját GYIK-ekkel, útmutatókkal, blogokkal, sőt, ha lehetséges, videókkal is.
Beépítse a kötelező szakaszokat
2019-ben a SmartBear, a Swagger fejlesztője felmérést készített az API fejlesztők és felhasználók körében. Megtudták, hogy a közösség milyen dokumentációs funkciókat tart a legfontosabbnak, így kaptunk egy listát a kötelezően szükséges dokumentációs szakaszokról, amelyeket a fejlesztők le akarnak fedni. Ezek közül néhányat végigveszünk.
A SmartBear 3000 API-gyakorlót kérdezett meg
Példák. A példákat általában kódrészletek formájában mutatják be, amelyek elég hasznosak, de még praktikusabbá tehetőek. Például a mezők átiratának beillesztésével, ahogyan azt a Medium dokumentációjában teszik, vagy akár egy mock API létrehozásával, amelyet a fejlesztők valódi hívásokkal tesztelhetnek és használhatnak. A mock API-kat könnyen meg lehet osztani egy URL-címen vagy a GitHubon keresztül, és ha bizonyos részletességgel elkészülnek, akár a végtermékben is felhasználhatók.
Státusz és hibák. Vannak szabványos állapotkódok és az API-jára specifikusak. Jó ötlet az összes olyan hibát feltüntetni, amelyet az API-ja kiválthat. A hibák gyakran a dokumentáció egy külön oldalára kerülnek, de érdemes néhányat közvetlenül a végpont alá duplikálni, ahol a legtöbbször felbukkannak.
Autentikáció. A legtöbb API-dokumentáció a hitelesítéssel és az engedélyezéssel kezdődik. Ennek tartalmaznia kell az API-kulcs megszerzésével és a kérelmek hitelesítésével kapcsolatos információkat, beleértve a lehetséges hibákat, a tokenek lejárati idejét és a hitelesítés érzékenységének magyarázatát (alapvetően emlékeztetve arra, hogy a kulcsok nem oszthatók meg, és hogy hol használhatók).
HTTP-kérelmek. A webes kérések HTTP-ben történő megadása a dokumentációhoz szükséges minimum. Általában feltételezik, hogy a fejlesztők tudják, hogyan kell HTTP-kéréseket küldeni az általuk választott nyelven, de néha az API-k készítői különböző nyelveken is tartalmaznak kéréseket. Ez automatikusan elvégezhető az API-specifikációs eszközökkel és az olyan API-kezelő eszközökkel, mint a Postman.
Iparági szabványos elrendezést használjon
Ha dokumentációgenerátort használ, az elrendezés már eleve el van döntve Ön helyett. A legtöbb API-dokumentáció ugyanúgy néz ki. Ha már használtál néhányat, akkor tudod, hogyan közelítsd meg az új dokumentációkat. Mégis, a nagy mennyiségű adat megszervezése, kereshetővé és könnyen navigálhatóvá tétele összetett feladat. Íme a legfunkcionálisabb elrendezés néhány jellemzője.
Dinamikus elrendezés. Egy elavult API-t a statikus dokumentációjáról lehet felismerni. Egyetlen oldal vagy akár egy PDF-dokumentum nem elég 2020-ban. A dinamikus dokumentációkat könnyű átnézni, frissíteni és könyvjelzővel ellátni.
Ragadós tartalom. Nem, a navigációs sáv nem vonja el a figyelmet, és nem is rabol értékes képernyőteret. Mindig szem előtt tartja a tartalmat.
Három oszlopos elrendezés. Nem túl gyakran használt, ez az elrendezés lehetővé teszi, hogy a jobb oldalon egy másik oszlop is legyen a kódpéldáknak. Ennek persze csak akkor van értelme, ha rengeteg szöveged van, és ki akarod emelni a kódot, hogy a felhasználóknak ne kelljen előre-hátra görgetniük vagy a lapok között váltogatniuk.
A HubSpot API-dokumentumok háromoszlopos elrendezést használnak
Kontrasztos színeket használj a szintaxishoz. A fejlesztők sok időt töltenek a kódpéldák nézegetésével, ezért tegye azokat olvashatóvá, és színnel különítse el a különböző komponenseket.
Ez a példa a Facebook Graph API dokumentációjából azt is mutatja, hogyan használhat különböző lapokat az SDK-k közötti választásra
Mentett görgetési állapot. Ez egy apró részlet, amelyet minden fejlesztő értékelni fog. Horgonyhivatkozásokat is használhat az oldal különböző részeinek megadására, arra az esetre, ha bemásolnák az URL-t.
Bátorítsa a visszajelzéseket. A dokumentációid a fő marketingeszközöd – ha az emberek szeretik őket, akkor az API-dat fogják használni a versenytársakéval szemben, és a közösséget is köréjük terelik. A szokásos “Hasznos volt ez az oldal?” üzenetből megtudhatod, hogy mennyire jól válaszolsz a fejlesztők kérdéseire, és a visszajelző űrlapot gyakran fogják használni, amíg teljesíted azt.
Ne hagyd el a dokumentációdat
Az API-felhasználók legnagyobb bosszúsága az elavult dokumentáció. Ez egyben az egyik leggyakoribb hiba is. A fejlesztők gyakran csak napokkal a frissítések bevezetése után írnak a frissítésekről, néha néhány mondatra szorítkozva. Ez azért történik, mert nincs kialakult folyamat a dokumentáció frissítésére, és senki sem felelős érte. Íme, hogyan biztosíthatod a rendszeres és hasznos dokumentumfrissítéseket.
Készítsd elő a dokumentumokat a frissítések előtt. Legyen ez egy további lépés az indítási tervben, ne dobja ki őket, mielőtt nem rendelkezik jól megírt, részletes és szerkesztett bekezdésekkel a frissítések bevezetéséhez.
Rendszeresen távolítsa el az elavult adatokat. A dokumentumokat gyakran, legalább néhány havonta egyszer felül kell vizsgálni. A felhasználói visszajelzési funkciók segítségével hamarabb észreveheti a következetlenségeket, és mindig kell lennie egy csapattagnak, aki felelős azok felülvizsgálatáért és a frissítésekre való reagálásért.
Használja az analitikát a dokumentációk javításához. A szabványos API-analitika elárulja, hogy mely végpontokat használják gyakrabban, így a dokumentáció bizonyos részeire összpontosíthat, és hasznosabb információkat adhat, vagy dedikált oktatóanyagokat készíthet. Figyelje, hogy milyen felhasználási esetekre használják az API-it, mert ez lehetővé teszi, hogy kiszélesítse az értékajánlatot, és több lehetőséggel frissítse a dokumentációt.
Nagyszerű API dokumentációs példák
Tonnaszámra vannak jó dokumentációk, amelyeket felfedezhet és amelyekből tanulhat. A cikk során megosztott példákon kívül itt van még néhány, amelyeket élvezhet és figyelembe vehet.
Medium API dokumentáció
A Medium API dokumentációi nem feltétlenül tartják be az általunk ma felsorolt összes szabályt, de nagyszerűek az API által támogatott korlátozott funkcionalitáshoz – a publikációk közzétételéhez és kereséséhez a Mediumon. A GitHubon vannak megosztva, valóban rövid, de világos tartalmuk van, rengeteg példával, és mindegyik a kódban említett összes paraméter átiratával zárul, beleértve az esetleges hibákat is. Figyelemre méltóan egyszerű, de megbízható – minden javaslat közvetlenül a GitHubon tehető, és a dokumentációt rendszeresen frissítik.”
Mailchimp API dokumentáció
AMailchimp felismerte, hogy közönségének nagy része marketingszakember, és olyan nyelvet használ, amely lehetővé teszi, hogy a nem műszaki szakemberek is megértsék, hogyan kell az API-ival dolgozni. Ránézésre minden egyes szakasz ugyanazt a struktúrát követi:
- mire képes egy végpont, és mit tesz lehetővé az útmutató a felhasználók számára
- mire lesz szüksége – bármilyen hozzáférésre vagy fiókra, amit a felhasználónak előbb meg kell szereznie
- milyen funkciót tartalmaz egy szöveges leírás, egy kódpélda több nyelven, és néha képernyőképek a felületről.
Még egy másolás gomb is van minden egyes kódrészlethez – ezt a részletet a nem műszaki szakemberek biztosan értékelni fogják.
Twilio API dokumentáció
A Twilio híresen jó API dokumentációval rendelkezik. Bár a dokumentáció csak a jéghegy csúcsa a Twilio által megosztott segítségnek – több nyelven is vannak SDK-k és mintaalkalmazások iOS-re, Androidra és webre. Először is, követik a három oszlopos logikát a kóddal közvetlenül az útmutató jobb oldalán. A legegyszerűbb műveleteket részletesen elmagyarázzák, és rengeteg linket tartalmaznak a további információkhoz és képernyőképekhez. A visszajelzéseket is ösztönzik egy “Rate this page” (Értékeld ezt az oldalt) gombbal, valamint a támogatási csapatra és a StackOverflow-n található címkére mutató linkekkel.
Spotify API dokumentáció
Bár a Spotify webes API dokumentációja nagyon tipikus, a Spotify for Developers platformon rengeteg további információval rendelkeznek. Vannak demók az alapfunkciókhoz, mock alkalmazások, Spotify API-k és widgetek felhasználásával épített élő példák, wrapperek különböző programozási nyelvekhez, és természetesen a konzol. A konzol lényegében egy interaktív dokumentáció, ahol kitöltheti a saját (vagy minta)adatait, és élőben fedezheti fel a végpontokat. A hatékony termékek az erős tudásbázissal együtt megbízható partnerré teszik a Spotify-t, amellyel a fejlesztők szívesen dolgoznak együtt.
Gondosan bánj a dokumentációval
A dokumentáció az egyetlen érintkezési pont, amelyet a közönséged nagy részével használsz, ezért meg kell tanulnod világosan kommunikálni rajta keresztül. A legjobb tipp itt az, ha valakinek a feladatává teszed. Gyakran egy olyan műszaki íróról van szó, aki tudja, hogyan kell megszólítani a különböző készségekkel rendelkező közönséget, aki képes a fejlesztők szavait megvalósítható pontokra fordítani, aki felügyeli a dokumentáció időben történő karbantartását és frissítését. A nagyszerű dokumentáció kezelése azonban szakértő nélkül is lehetséges. Az olyan API-kezelő eszközök, mint a Swagger UI, a Spotlight, az Apiary és a docs specifikációs eszközök széles körű funkcionalitással rendelkeznek, amelyek segítségével olyan docsokat készíthet, amelyeket a fejlesztők szeretni fognak.