Useimmat kehittäjät luulevat, että API-dokumentaatio on ihmisiä varten. Näin ei enää ole.
Kun insinöörit kysyvät ChatGPT:ltä, miten API:lla tunnistaudutaan, miten webhook rakennetaan tai miten käyttörajoituksia hallitaan, dokumentaatiosi kilpailee suoraan 50 muun lähteen kanssa tekoälyjärjestelmän arvioinnissa. Tekoälymoottorit arvioivat teknistä dokumentaatiota ensisijaisina lähteinä. Hyvin jäsennelty API-referenssi voi saada satoja viittauksia kuukaudessa. Huonosti optimoitu jää kokonaan huomiotta.
Ongelma on se, että teknistä dokumentaatiota ei ole rakennettu tekoälyä varten. Se on rakennettu ihmisille, jotka hakevat Googlella, klikkaavat linkkejä ja lukevat vaihe vaiheelta. Tekoälyjärjestelmät lukevat eri tavalla. Ne poimivat, pilkkovat, yhdistävät lähteeseen ja viittaavat. Dokumentaatiosi rakenne, koodiesimerkit ja versiointi vaikuttavat siihen, löytääkö tekoälyjärjestelmä sisältösi, ymmärtääkö se sen ja viittaako siihen. Tässä luvussa käydään läpi, miltä teknisen dokumentaation optimointi näyttää ja mitkä muutokset tekevät dokumenteistasi näkymättömistä välttämättömiä.
Mitä on teknisen dokumentaation optimointi tekoälyä varten?
Teknisen dokumentaation optimointi tekoälyä varten tarkoittaa API-referenssien, käyttöönotto-oppaiden, virhedokumentaation ja koodiesimerkkien rakentamista niin, että tekoälyrobotit voivat jäsentää, poimia, yhdistää lähteeseen ja lainata niitä oikein. Toisin kuin perinteinen SEO, joka optimoi linkkien seuraamista ja hakusanojen vastaavuutta, dokumentaation optimointi tekoälyä varten keskittyy merkitysten selkeyteen, poimittavuuteen ja faktatiheyteen.
Tekoälyjärjestelmä, joka indeksoi dokumenttisi, tekee kolme asiaa. Se käy sivusi läpi lukeakseen ne (indeksoitavuus). Se tallentaa sisältösi osat erillisinä palasina, jotka voi hakea, kun ne ovat olennaisia (pilkkominen). Ja se päättää, viittaako se sinun palaasi lähteenä vastausta tehdessään (viittauskelpoisuus). Useimmat dokumentaatiot epäonnistuvat yhdessä tai useammassa näistä vaiheista.
Miksi tekoälyviittauksilla on väliä tekniselle sisällölle
Tekninen dokumentaatio on yksi tekoälyjärjestelmien luotetuimmista sisältötyypeistä. Kun kehittäjä kysyy ChatGPT:ltä, miten API:asi käytetään, järjestelmä painottaa teknistä dokumentaatiota enemmän kuin blogikirjoituksia tai foorumikeskusteluja, koska API:t vaativat tarkkuutta. Väärä päätepiste, puuttuva parametri tai virheellinen tunnistautumistapa rikkoo integraation.
Tekoälyjärjestelmät palkitsevat tämän käsityksen. API-referenssidokumentaatioosi viitataan todennäköisemmin kuin blogisisältöösi, koska se on tarkempaa, helpommin todennettavaa ja täydellisempää. Ongelma on, että kehittäjät eivät löydä sinua tekoälyhaun kautta samalla tavalla kuin blogisisältöä. He löytävät sinut suorilla haulla API:stasi, puskaradion kautta ja varhaisina käyttäjinä. Kun he löytävät dokumentaatiosi, tekemäsi optimointi ratkaisee, löytävätkö muut kehittäjät ratkaisusi tekoälyn kautta.
Miten tekoälyjärjestelmät lukevat ja poimivat teknistä dokumentaatiota
Tekoälyrobotit käsittelevät dokumentaatiotasi kuin jäsenneltyä tietokantaa, eivät kertomusta. Näin käy, kun tekoälyjärjestelmä indeksoi dokumenttisi.
Ensin robotti pyytää sivusi (tai dokumentaatioalustasi tarjoaa sen API:n kautta). Jos dokumenttisi on rakennettu JavaScript-kehyksillä ilman palvelinpuolen _blocked_öintiä, robotti saa tyhjän HTML:n. Tämä on yksi yleisimmistä virheistä. Jos dokumenttisi on tehty Gatsbylla, Next.js:llä tai vastaavalla kehyksellä, varmista, että web-hotellisi tai dokumentaatioalustasi _blocked_öi sivut palvelinpuolella. Muuten sisältösi on useimmille tekoälyroboteille näkymätöntä.
Toiseksi järjestelmä pilkkoo sivusi. Se ei tallenna koko 4 000 sanan API-referenssiäsi yhtenä lohkona. Se jakaa sen osiin, yleensä 100-300 sanan mittaisiin. Otsikkohierarkialla on tässä valtava merkitys. Jos ohitat otsikkotasoja (hyppäät H1:stä H3:een), järjestelmä sekoaa siitä, mikä sisältö kuuluu minnekin. Jos otsikkosi ovat epämääräisiä ("Yleiskatsaus" otsikon "Tunnistautumistavat" sijaan), järjestelmä ei voi tietää, mitä kukin osa kattaa lukematta jokaista sanaa.
Kolmanneksi järjestelmä liittää jokaiseen palaan metatietoa. Se lukee otsikkosi, kappaleen tekstin, koodiesimerkit ja jäsennellyn datan (schema-merkinnät) ymmärtääkseen, mistä pala kertoo. Sitten se tallentaa palan vektoritietokantaan, jossa samankaltaiset käsitteet ryhmittyvät yhteen. Kun kehittäjä esittää kysymyksen, järjestelmä etsii kysymysvektorin lähellä olevat ryhmät ja hakee olennaisimmat palat.
Neljänneksi järjestelmä päättää, viittaako se palaasi. Se riippuu faktatiheydestä, selkeydestä, tarkkuudesta ja siitä, löytyykö tieto muualta. Yleiseen selitykseen otsikoiden asettamisesta viitataan harvemmin kuin tarkkaan esimerkkiin, joka näyttää, mitä otsikoita API:si vaatii.
Optimoi dokumentaation rakenne tekoälyn poimittavaksi
Otsikkohierarkiasi on tehokkain optimointityökalusi. Käytä johdonmukaisia, tarkkoja H2- ja H3-otsikoita, jotka kertovat järjestelmälle tarkasti, mitä kukin osa kattaa.
Käytä tarkkoja ja täydellisiä otsikoita
VÄÄRIN otsikoitu: "Tunnistautuminen"
OIKEIN otsikoitu: "Miten API-pyynnöt tunnistetaan"
Oikea versio kertoo järjestelmälle, että tässä osassa on toimivaa tietoa tunnistautumisesta. Väärä versio on epäselvä. Se voisi kertoa, miksi tunnistautuminen on olemassa, miten se toimii tai mitä tehdä, jos se epäonnistuu. Ole tarkka.
Sovita otsikkorakenne sisällön hierarkiaan
Jos API:ssasi on useita tunnistautumistapoja (API-avain, OAuth, JWT), käytä jokaiselle H3-alaotsikkoa, älä luettelomerkkejä tai lihavointia. Luettelomerkit sopivat kohtien listaamiseen. Ne eivät sovi nimetyille osille, jotka tarvitsevat oman rakenteensa.
Hyvä rakenne
- H2: Miten API-pyynnöt tunnistetaan
- H3: Tunnistautuminen API-avaimella
- H3: Tunnistautuminen OAuth 2.0:lla
- H3: Tunnistautuminen JWT:llä
Tämä rakenne kertoo järjestelmälle, että tunnistautuminen on pääaihe ja sen alla on kolme erillistä tapaa. Järjestelmä voi poimia OAuth-osion erikseen ja viitata siihen, kun kehittäjä kysyy nimenomaan OAuthista.
Kirjoita vaiheille selvät johdannot
Jos annat vaiheiden sarjan, kerro se selvästi. Älä oleta, että järjestelmä ymmärtää luettelomerkkiesi olevan vaiheita.
VÄÄRIN: "Tunnistaudu lisäämällä API-avaimesi pyynnön otsikkoon. Käytä otsikon nimeä Authorization. Muotoile arvoksi Bearer YOUR_API_KEY."
OIKEIN: "Tunnistat API-pyyntösi kolmella vaiheella. Etsi ensin API-avaimesi WEMASY-tilisi asetuksista. Lisää toiseksi pyyntöösi Authorization-otsikko. Muotoile kolmanneksi arvoksi Bearer YOUR_API_KEY."
Oikea versio käyttää selvää kieltä, joka kertoo järjestelmälle, että nämä ovat peräkkäisiä vaiheita, ei toisiinsa liittyviä faktoja.
Tee koodiesimerkeistäsi poimintavalmiita
Koodiesimerkit ovat teknisen dokumentaation useimmin lainattu sisältötyyppi. Tekoälyjärjestelmät viittaavat mielellään koodiin, koska se on yksiselitteistä. Kaikki koodiesimerkit eivät kuitenkaan ole yhtä hyviä. Tapa, jolla esität koodin, vaikuttaa siihen, voiko järjestelmä poimia ja lainata sen oikein.
Yhdistä koodi edeltävään tekstiin, joka selittää, mitä koodi tekee
Älä jätä koodilohkoja yksin. Jokaista koodiesimerkkiä pitäisi edeltää lause, joka kertoo, mitä se havainnollistaa.
VÄÄRÄ rakenne
[Koodilohko]
[Selityskappale]
OIKEA rakenne
[Selityslause]
[Koodilohko]
[Lisätietoa tai virheenkäsittely]
Edeltävä selitys kertoo järjestelmälle, mitä koodilta voi odottaa. Se antaa myös asiayhteyden, johon järjestelmä voi viitata ennen kuin se näyttää itse koodin.
Pidä esimerkit yhdessä tehtävässä
Älä näytä 50 rivin koodiesimerkkiä, joka havainnollistaa viittä eri asiaa. Jaa se useaan esimerkkiin, joista jokainen näyttää yhden tietyn toiminnon. Koodiesimerkkiä poimivan tekoälyjärjestelmän täytyy olla varma, että esimerkki on todella täydellinen eikä riipu muualla näytetystä käyttöönotosta.
Sisällytä esimerkkeihin virheenkäsittely
Oikeat kehittäjät kysyvät aina virheistä. Jos koodiesimerkistäsi puuttuu virheenkäsittely, kehittäjät kysyvät tekoälyjärjestelmältä, mitä tapahtuu, kun koodi epäonnistuu. Jos dokumentaatiosi ei vastaa siihen, tekoälyjärjestelmä viittaa jonkun toisen dokumentaatioon, joka vastaa. Lisää try-catch-lohkot, virhevastaukset tai selvät huomautukset siitä, mitä virheitä toiminto voi palauttaa.
Rakenna API-referenssin päätepisteet tekoälyn ymmärrettäviksi
API:si päätepisteiden referenssi on tärkein dokumentaatiosi tekoälyviittauksia ajatellen. Tee jokaisesta päätepisteestä itsenäisesti ymmärrettävä, niin ettei lukijan tarvitse hypätä sivujen välillä.
Aloita jokainen päätepiste kertomalla, mitä se tekee
Älä aloita päätepisteen referenssiä sanoilla "Users-päätepiste palauttaa käyttäjädataa." Aloita kokonaisella lauseella, joka selittää toiminnon.
VÄÄRIN: "/users-päätepiste antaa pääsyn käyttäjätietueisiin."
OIKEIN: "Hae lista kaikista työtilasi käyttäjistä."
Oikea versio on toiminto. Se kertoo järjestelmälle tarkasti, mitä tämä päätepiste tekee, ilman että järjestelmän täytyy päätellä se polusta.
Sisällytä jokaiseen päätepisteen osioon täydellinen pyyntörakenne
Älä viittaa yhteiseen "Tunnistautuminen"-osioon ja oleta, että järjestelmä yhdistää tiedot. Kerro jokaisen päätepisteen dokumentaatiossa, miten tunnistaudutaan, mitkä otsikot lisätään ja miltä täydellinen pyyntö näyttää. Näin jokainen päätepiste on poimittavissa itsenäisesti.
Näytä sekä onnistuneet että epäonnistuneet vastaukset
Dokumentoi, miltä onnistunut vastaus näyttää. Dokumentoi sitten, miltä virhevastaukset näyttävät. Sisällytä vähintään yksi esimerkki jokaisesta yleisestä virhetilanteesta (401 Unauthorized, 404 Not Found, 429 Rate Limited). Kun tekoälyjärjestelmällä on sekä onnistuneet että virhevastaukset, se voi antaa kehittäjille täydellisempää ohjausta.
Hoida versiointi tekoälynäkyvyyttä varten
Monella API:lla on useita versioita. V1, V2 ja joskus vanhoja versioita, jotka ovat yhä tuotannossa. Versiointi aiheuttaa tekoälyjärjestelmille erityisen ongelman. Mihin versioon pitäisi viitata, kun joku kysyy API:stasi?
Useimmat tekoälyjärjestelmät viittaavat uusimpaan löytämäänsä versioon. Jos nykyinen versiosi on v3, mutta dokumentaatioalustasi tekee v1:n ja v2:n yhtä helposti löydettäviksi, järjestelmä voi viitata vanhaan versioon ja jättää kehittäjät vanhentuneiden ohjeiden varaan.
Käytä URL-rakennetta, joka kertoo version tärkeysjärjestyksen
Jos mahdollista, pidä nykyinen dokumentaatio selkeässä URL-osoitteessa (/docs/api) ja vanhemmat versiot versioiduissa osoitteissa (/docs/api/v1, /docs/api/v2). Tämä kertoo tekoälyjärjestelmille, että versioimaton URL on nykyinen, suositeltu versio.
Lisää versioilmoitukset vanhaan dokumentaatioon
Jos ylläpidät vanhempien versioiden dokumentaatiota (koska kehittäjät käyttävät niitä yhä), lisää sivun alkuun selkeä versioilmoitus. Älä oleta, että järjestelmä lukee URL-osoitteesi ja ymmärtää, mitä versiota se katsoo.
HYVÄ ilmoitus: "Katsot API v1:n dokumentaatiota. Tämä versio on poistumassa käytöstä, ja se poistetaan 1. tammikuuta 2027. Suosittelemme päivittämään API v3:een. Katso päivitysopas."
Tee käytöstä poistaminen selväksi. Kerro päättymispäivä. Linkitä nykyiseen versioon ja siirtymäoppaaseen. Tämä antaa järjestelmälle kaiken, mitä se tarvitsee asettaakseen vanhentuneen dokumentaation oikeaan yhteyteen.
Tee poimittavia integraatio-oppaita ja ohjeita
Integraatio-oppaat eroavat API-referensseistä. Ne ovat kerronnallisia, tehtäväkeskeisiä ja suunnattu kehittäjille, jotka toteuttavat tiettyjä työnkulkuja. Tekoälyjärjestelmät viittaavat niihin eri tavalla.
Aloita lopputilasta, älä selityksestä
Webhook-vastaanottimen rakentamista käsittelevän integraatio-oppaan pitäisi alkaa sillä, miltä toimiva webhook-vastaanotin näyttää. Näytä sitten vaiheet sen rakentamiseen. Näytä sitten, miten sitä testataan.
Tällä järjestyksellä on väliä, koska tekoälyjärjestelmät poimivat osioita erikseen. Jos kehittäjä kysyy "miten kuuntelen webhook-tapahtumia", järjestelmä voi hakea webhook-kuuntelijoita käsittelevän osiosi. Sen osion pitäisi olla niin täydellinen, että se kelpaa sellaisenaan.
Käytä numeroituja vaiheita ja selkeitä päätöskohtia
Ehdollisen logiikan pitäisi olla selvää. Älä sano "jos tarvitset tapahtumien suodatusta, lisää tämä koodi." Esitä sen sijaan suora kysymys otsikkona.
OIKEA rakenne
Vaihe 1: Luo webhook-päätepiste
Vaihe 2: Rekisteröi päätepisteesi URL
Vaihe 3: Käsittele saapuvat webhookit
Vaihe 4: Pitäisikö tapahtumia suodattaa? (Kyllä / Ei)
- Jos kyllä: Lisää tapahtumien suodatus
- Jos ei: Siirry testaukseen
Vaihe 5: Testaa webhookisi
Tämä rakenne tekee tekoälyjärjestelmälle selväksi, missä ehdollinen logiikka on ja mitkä vaihtoehdot ovat.
Merkitse dokumentaatiosi jäsennellyllä datalla
Schema-merkintä kertoo tekoälyjärjestelmille, millaista sisältöä ne lukevat. Käyttöönotto-opas? API-referenssi? Ohje? Jäsennelty data tekee tarkoituksen selväksi.
Käytä Article-schemaa oppaille ja integraatiodokumentaatiolle
Kaikessa dokumentaatiossa, joka on enemmän kuin referenssisivu, pitäisi käyttää Article-schemaa. Lisää kirjoittaja, julkaisupäivä ja viimeisin muokkauspäivä. Tämä auttaa järjestelmää ymmärtämään auktoriteettia ja tuoreutta.
Käytä HowTo-schemaa vaiheittaisille oppaille
Jos dokumentaatiossasi on numeroituja vaiheita, käytä HowTo-schemaa. Lisää jokainen vaihe nimen ja kuvauksen kanssa. Tämä auttaa järjestelmää poimimaan yksittäiset vaiheet ja viittaamaan olennaiseen.
Käytä FAQPage-schemaa yleisille kysymyksille
Jos dokumenteissasi on UKK-osio, merkitse se. Älä oleta, että järjestelmä tunnistaa sen UKK:ksi.
Miten WEMASY tukee teknistä dokumentaatiota
WEMASYn Sivustonrakentajassa on työkaluja, jotka helpottavat teknisen dokumentaation rakennetta. Voit tehdä selkeät otsikkohierarkiat, upottaa oikein muotoillut koodilohkot ja jäsentää monisivuisen dokumentaation johdonmukaisiksi kokonaisuuksiksi. WEMASY hoitaa myös palvelinpuolen _blocked_öinnin automaattisesti, joten tekoälyjärjestelmät voivat indeksoida dokumentaatiosi täysin. Katso, mitä kukin paketti sisältää.
Usein kysytyt kysymykset
Tarvitseeko tekninen dokumentaationi oman verkkotunnuksen?
Ei. Dokumentaatiosi voi olla osoitteessa docs.yourbrand.com, yourbrand.com/docs tai vaikka yourbrand.com/api. Tärkeää on, että dokumentaatio on julkisesti saatavilla, indeksoitavissa ja päivitetty johdonmukaisesti. Tekoälyjärjestelmät viittaavat dokumentaatioon riippumatta siitä, missä se sijaitsee. Oman verkkotunnuksen avulla voit kuitenkin seurata tekoälyliikennettä erikseen pääsivustosi liikenteestä. WEMASYn Sivustonrakentajalla voit tehdä tämän suoraan verkkosivustollasi.
Kuinka usein minun pitäisi päivittää API-dokumentaationi?
Päivitä dokumentaatiosi aina, kun julkaiset API-muutoksia. Lisää muutosloki, jonka tekoälyrobotit näkevät ja joka näyttää, mitä muuttui ja milloin. Tekoälyjärjestelmät painottavat tuoretta dokumentaatiota enemmän kuin vanhentunutta. Jos julkaisit API v3:n kuusi kuukautta sitten, mutta v2-dokumentaatiosi sijoittuu hakutuloksissa korkeammalle, kyse on sisällön tuoreudesta. Pidä nykyinen versio ajan tasalla.
Mitä eroa on ihmisille ja tekoälylle tehdyllä dokumentaatiolla?
Ihmisille tehty dokumentaatio voi olla kerronnallista ja olettaa asiayhteyden. Tekoälylle tehdyn dokumentaation täytyy olla selvää ja itsenäistä. Ihmislukija muistaa, että mainitsit tunnistautumisen aiemmin oppaassa. Yksittäistä osiota poimiva tekoälyjärjestelmä ei muista. Kirjoita niin kuin jokainen osio luettaisiin erillään. Sisällytä kaikki asiayhteys, jota osion ymmärtämiseen tarvitaan ilman hyppäämistä muualle.
Ovatko koodiesimerkit vai tekstiselitykset tärkeämpiä tekoälyviittauksille?
Koodiesimerkkeihin viitataan useimmin, koska ne ovat konkreettisia ja yksiselitteisiä. Koodiin ilman selitystä viitataan kuitenkin harvemmin kuin koodiin, jonka edellä on selkeä johdantolause. Eniten viitattu dokumentaatio yhdistää selkeät selitykset ja toimivat koodiesimerkit.
Pitäisikö minun sallia tekoälyrobottien indeksoida dokumentaationi?
Kyllä, ellei sinulla ole erityistä syytä olla sallimatta. Jos dokumentaatiosi on kilpailuetu etkä halua sen saavan viittauksia, voit estää tekoälyrobotit robots.txt:llä. Useimmat API:t kuitenkin hyötyvät tekoälyjärjestelmien viittauksista, koska ne tuovat päteviä kehittäjiä. Robottien estäminen tarkoittaa, että kehittäjät käyttävät kilpailevia API:ita, jotka ovat näkyvämpiä tekoälyhaussa.
Mitkä tekniset GEO-työkalut auttavat seuraamaan, saako dokumentaationi viittauksia?
Käytä tekoälynäkyvyyden seurantatyökaluja seurataksesi, mihin dokumentaatiosivuihisi ChatGPT, Perplexity, Claude ja muut tekoälyjärjestelmät viittaavat. Testaa dokumentaatiotasi myös käsin kysymällä ChatGPT:ltä ja Claudelta API:si ominaisuuksista. Jos dokumentaatiosi näkyy vastauksissa, optimointi toimii. Jos vastauksissa näkyvät kilpailijat, sinulla on optimointityötä tehtävänä.