Dokumentacja pokazuje przykład żądania, które działa na jednym idealnym dokumencie. Nie mówi, co zrobić przy duplikacie, braku pola, starym statusie i limicie. Deweloper wdraża integrację, a klient dowiaduje się o wyjątkach od pierwszego zgłoszenia. Strona technicznie jest świetna. Proces wymaga jeszcze szamanowania w logach.
Dokumentacja AI powinna prowadzić od zadania do potwierdzonego skutku. Opisuje kontrakt, wersje, błędy, uprawnienia i odbiór. SEO pomaga ją znaleźć, ale prawdziwym testem jest wdrożenie bez zgadywania.
Zacznij od rezultatu integracji
Opisz, co użytkownik osiąga: rekord w CRM, raport, odpowiedź, publikację lub zatwierdzony eksport. Samo „połącz się z API” nie jest celem. Pokaż, jak rozpoznać sukces w systemie docelowym.
Dodaj wymagane źródła, role, konto i wersję. Nie zaczynaj od pełnej listy endpointów. Najpierw jedna ścieżka z ograniczonym zakresem i danymi testowymi.
Jeżeli integracja obejmuje model, reguły i człowieka, oznacz te etapy. Czytelnik powinien wiedzieć, co jest deterministyczne, co wymaga odbioru i gdzie może powstać niepewność.
Kontrakt wejścia i wyniku
Opisz pola, typy, znaczenie, wymagalność, wartości puste i relacje. JSON i schemat pomagają walidować strukturę, ale nie rozstrzygają, czy „status” oznacza zgodę albo etap sprzedaży.
Dodaj przykład poprawny oraz przypadki brzegowe: brak, nowy enum, data ze strefą, polskie znaki, duplikat i nieznane pole. Każdy powinien mieć oczekiwane zachowanie, nie tylko komentarz „może się zdarzyć”.
Przy mapowaniu stosuj zasady z artykułu o semantyce pól AI. Dokumentacja powinna odpowiadać na pytania przed zapisem, nie dopiero po błędzie.
Wersja na samej górze
Podaj wersję API, modelu, schematu, promptu i przykładów. Nie mieszaj zrzutów z różnych wersji bez oznaczenia. Czytelnik musi wiedzieć, czy instrukcja dotyczy jego konfiguracji.
Zachowaj historię zmian z datą i skutkiem. Komunikat „ulepszono integrację” nie mówi, czy trzeba zmienić kod. Opisz wymagane działanie, datę graniczną i sposób testu.
Przy zmianie API pomocny jest artykuł o kompatybilności AI. Dokumentacja powinna prowadzić do migracji, a nie tylko nowego changelogu.
Błędy z następnym krokiem
Przy każdym typie błędu podaj znaczenie, skutek, możliwość ponowienia i właściciela. 400 nie zawsze oznacza to samo w twoim procesie. 429 wymaga innego działania niż 403. Timeout pozostawia wynik nieznany.
Nie pisz „spróbuj ponownie później” przy każdym przypadku. Przy błędzie walidacji popraw dane, przy autoryzacji konfigurację, przy limicie tempo. Przy nieznanym skutku sprawdź idempotencję przed nową operacją.
Dodaj identyfikator korelacji i sposób zgłoszenia. Nie wymagaj wysyłania pełnych dokumentów i sekretów do wsparcia. Log diagnostyczny powinien wystarczać do pierwszego etapu bez nowego wycieku.
Uprawnienia przed pierwszym wywołaniem
Pokaż minimalną rolę i zakres. Odczyt, zapis, publikacja i administracja są osobnymi decyzjami. Nie używaj administratora w przykładzie tylko dlatego, że łatwiej przejdzie test.
Dodaj test odmowy. Integracja nie powinna pobierać innych kolekcji ani zmieniać ustawień. Przy danych testowych sprawdź, czy sekret nie trafia do logów, adresów i przykładów.
Przy rolach pomocny jest artykuł o przeglądzie uprawnień automatyzacji AI. Dokumentacja powinna pokazywać zarówno poprawne działanie, jak i granicę.
Przykład kodu, który da się uruchomić
Użyj fikcyjnych danych, aktualnego formatu i pełnego przepływu. Nie pomijaj uwierzytelnienia, walidacji, obsługi błędów i sprawdzenia wyniku. Skrót kodu może być czytelny, ale nie powinien sugerować niebezpiecznej ścieżki.
Poniższy lokalny przykład w Node.js sprawdza fikcyjny identyfikator i wypisuje rekord. Nie łączy się z API ani nie wymaga sekretu:
node -e 'const d = { event_id: "evt_001" }; if (typeof d.event_id !== "string") process.exit(1); console.log(JSON.stringify(d));'
Oczekiwany wynik to {"event_id":"evt_001"}. Jest to tylko mały test typu pola, nie pełny przepływ integracji ani walidacja całego formatu identyfikatora. Rzeczywisty przykład połączenia musi osobno pokazać uwierzytelnienie, błędy, walidację i odbiór skutku zgodnie z dokumentacją używanego systemu.
Oznacz miejsce na sekret bez wklejania prawdziwej wartości. Nie umieszczaj tokenów w przeglądarce ani publicznym repozytorium przykładów. Link do bezpiecznej konfiguracji powinien być aktualny.
Przetestuj przykład po każdej istotnej zmianie. Kod, który tylko wygląda poprawnie, jest dokumentacyjną poezją. Uruchomienie i odbiór skutku daje dowód.
Wersja robocza i środowisko testowe
Opisz, jak odróżnić dane testowe od produkcji. Podaj dozwolonych odbiorców, limity, webhooki i sposób usunięcia. Samo słowo „sandbox” nie blokuje skutków.
Dodaj przypadki symulowane: limit, błąd serwera, duplikat, nieznany status i uprawnienie. Jeżeli środowisko nie potrafi ich wykonać, opisz bezpieczny sposób testu lokalnego.
Nie przenoś produkcyjnej bazy do testu dla realizmu. Fikcyjne dane powinny zachowywać trudność procesu bez identyfikowania osób. Po teście usuń kopie i odwołaj tokeny.
Odbiór w systemie docelowym
Pokaż, gdzie sprawdzić rekord, relacje, status, publiczny adres lub wiadomość. Odpowiedź 200 nie wystarcza. Integracja może zwrócić sukces z pustym wynikiem albo zapisać w złym znaczeniu.
Dodaj sumy kontrolne: liczba wejść, wyników, duplikatów i błędów. Przy ponowieniu porównaj skutek. Nie kończ instrukcji na „gotowe” bez otwarcia wyniku.
Przy monitoringu pomocny jest artykuł o obserwacji błędów integracji AI. Dokumentacja powinna prowadzić do sygnałów, które działają po wdrożeniu.
SEO dla pytań technicznych
Użyj naturalnych nazw błędów, pól, wersji i zadania. Title powinien odróżniać przewodnik wdrożenia od referencji API i artykułu marketingowego. Nagłówki odpowiadają etapom pracy.
Nie twórz osobnych stron dla każdej drobnej wersji bez potrzeby. Jeżeli użytkownicy nadal korzystają z poprzedniej, zachowaj ją z jasnym statusem i linkiem do aktualnej. Canonical nie powinien ukrywać wymaganej wersji.
Kod i istotne błędy powinny być dostępne jako tekst. Obrazek z JSON-em jest niewygodny dla użytkownika i trudny do wyszukania. Linki do powiązanych instrukcji muszą działać po zmianach adresów.
Linkowanie z produktu i artykułów
Strona funkcji powinna prowadzić do wdrożenia przy konkretnym zadaniu. Artykuł o mapowaniu lub błędach linkuje do właściwej sekcji, nie do ogólnej strony dokumentacji.
Z dokumentacji prowadź do cennika, limitów, bezpieczeństwa, wersji i wsparcia. Nie każdy link musi być sprzedażowy. Część najlepszych leadów powstaje, kiedy użytkownik widzi, że proces jest przemyślany.
Aeneia Audit pasuje przy mapie danych i odpowiedzialności. Aeneia Design pomaga zaprojektować czytelną architekturę dokumentacji. Nie wstawiaj usługi w środek przykładu kodu.
Przykład: webhook przychodzi dwa razy
W przykładowym logu pokaż również etap obsługi zdarzenia, na przykład przyjęcie i zakończenie przetwarzania. Dopisz, jak sprawdzić wynik, gdy połączenie urwało się przed otrzymaniem odpowiedzi, aby uniknąć niepotrzebnego ponowienia całej operacji.
Przykładowy, fikcyjny log bez danych osobowych może wyglądać tak:
event_id=evt_001 request_id=req_1 status=accepted
event_id=evt_001 request_id=req_1 status=completed
event_id=evt_001 request_id=req_2 status=duplicate_ignored
Oczekiwany rezultat testu to jeden skutek w docelowym systemie, mimo dwóch prób. Log jest wzorem do zaprojektowania testu, a nie dowodem działania konkretnego CRM. Sprawdź trwały zapis, obsługę awarii i równoczesnych prób.
Dodaj wariant z tym samym zdarzeniem i nowym identyfikatorem żądania. System powinien rozpoznać źródło, nie tylko techniczną próbę. Bez tego dokumentacja może nauczać deduplikacji niewłaściwego pola.
Przy idempotencji stosuj zasady z artykułu o ponowieniach integracji AI. Przykład powinien być zgodny z rzeczywistym zachowaniem produktu.
Przykład: nowy status w odpowiedzi
Model zwraca wartość, której schemat nie zna. Instrukcja nie może sugerować przypisania najbliższego enumu. Zadanie trafia do kolejki błędów z wersją i źródłem.
Opisz komunikat dla użytkownika, zachowanie zapisu i rolę właściciela. Po aktualizacji mapy powtórz stary i nowy przypadek. Nie przepisuj historii na nowe znaczenie bez decyzji.
Taki przykład pokazuje różnicę między poprawnością typu a poprawnością biznesową. To często najważniejsza lekcja integracji AI i warta osobnego miejsca.
Test dokumentacji przez nową osobę
Poproś dewelopera lub osobę techniczną spoza wdrożenia o wykonanie instrukcji na danych testowych. Nie odpowiadaj na pytania w trakcie. Zapisz miejsca, w których szuka hasła, wersji, błędu lub wyniku.
Jeżeli musi kontaktować się z autorem, dopisz brakujący krok. Nie tłumacz problemu „doświadczeniem”. Dokumentacja ma przenosić wiedzę, a nie testować telepatię.
Po wdrożeniu sprawdź linki, kod, wersje, szybkość i dostępność. Odbiór obejmuje również telefon, klawiaturę i kopiowanie przykładów. Potem powtórz tylko zależne przypadki po zmianie.
Utrzymanie przy każdej wersji
Przypisz właściciela dokumentacji i termin przeglądu. Zmiana API powinna automatycznie tworzyć zadania dla zależnych przewodników. Nie zostawiaj aktualizacji dla jednej osoby pamiętającej wszystko.
Raportuj nieaktualne strony i błędy linków. Otwieraj najczęściej używane instrukcje oraz krytyczne błędy. Nie czytaj całej dokumentacji po równo przy każdej wersji.
Usuwaj stare porady tylko po sprawdzeniu użytkowników i zależności. Archiwum powinno mieć status i prowadzić do aktualnej wersji. Przestarzały przykład bez oznaczenia jest gorszy niż brak przykładu.
Minimalny pakiet przed publikacją
Przygotuj jedną ścieżkę, kontrakt, role, błędy, testy, wersję i odbiór. Dodaj źródła i datę. Nie publikuj dziesięciu endpointów bez jednego działającego procesu.
Zachowaj pytania nierozstrzygnięte i sposób zgłoszenia. Dokumentacja może być krótka, jeśli nie zgaduje. Lepiej dopisać ograniczenie niż obiecać pełną kompatybilność.
Po publikacji obserwuj zgłoszenia i powtarzalne pytania. Każde z nich jest kandydatem do poprawki instrukcji lub produktu. Nie dokładaj FAQ bez rozwiązania przyczyny.
Dokumentacja jako część produktu
Traktuj błędy instrukcji jak błędy interfejsu. Jeżeli użytkownicy zapisują zły status, bo przykład tak sugeruje, nie wystarczy wysłać im link do poprawki. Zmień przykład, komunikat i test. Powtarzalne pytanie może wskazywać na zły kontrakt produktu, a nie na czytelnika.
Zbierz krótką listę najczęstszych problemów z wdrożenia i przypisz im właścicieli. Część należy do dokumentacji, część do API, a część do wsparcia. Nie wysyłaj wszystkiego do redaktora. Tekst nie naprawi niejednoznacznego enuma ani losowego timeoutu, choć potrafi je uczciwie opisać.
Wersja podstawowa i zaawansowana
Pierwsza ścieżka powinna pozwolić uruchomić jedno zadanie bez znajomości całej platformy. Dopiero później pokazuj routing, fallback i niestandardowe mapowania. Zaawansowana konfiguracja na początku zwiększa liczbę decyzji przed pierwszym sukcesem.
Nie usuwaj jednak zabezpieczeń dla prostoty. Wersja podstawowa nadal wymaga minimalnych ról, walidacji i odbioru. Możesz odłożyć dodatkowe funkcje, ale nie test odmowy. Czytelnik powinien zakończyć pierwszy etap z działającym i ograniczonym procesem, nie z administratorem i pustym budżetem.
Dowód aktualności przykładów
Przy każdym kluczowym przykładzie zapisz datę ostatniego uruchomienia i wersję. Automatyczny test może sprawdzać format oraz skutek, a przegląd redakcyjny ocenia sens opisu. Sam fakt, że CI jest zielone, nie oznacza, że instrukcja jest zrozumiała.
Przy zmianie dostawcy nie oznaczaj przykładu jako aktualnego na podstawie samego statusu 200. Otwórz wynik i porównaj pola, relacje oraz błędy. Dokumentacja ma pokazywać rzeczywiste zachowanie, a nie tylko obecność odpowiedzi z serwera.
Aeneia Design pomaga zorganizować dokumentację i doświadczenie wdrożenia. Przy architekturze treści pomocny jest przewodnik Aeneia Signal.
Przed publikacją przejdź instrukcję na koncie testowym, zaczynając od opisanych wymagań. Zanotuj wersję interfejsu, potrzebne uprawnienia i oczekiwany rezultat, a przy błędzie podaj sposób rozpoznania problemu. Osoba korzystająca z dokumentacji powinna móc odróżnić wykonaną operację od samego przyjęcia żądania przez usługę.
Sprawdź nas. To zdrowe.
Temat zmienia się szybko. Linki prowadzą do źródeł pierwotnych i stron, na których możesz zweryfikować kontekst.
