Help desk. Dokumentacja produktowa dostępna wtedy, kiedy jest potrzebna

01. Punkt wyjścia

Klient sprzedaje urządzenia, które ktoś musi zamontować, uruchomić i serwisować. Każdy produkt ma własny komplet dokumentów: instrukcję obsługi, instrukcję instalacji, dokumentację techniczną, karty katalogowe. Dokumenty występują w trzech wersjach językowych i są aktualizowane wraz z kolejnymi rewizjami produktu.

Odbiorcą tej wiedzy nie jest klient końcowy, tylko instalator i partner handlowy. Ta różnica jest istotna, bo instalator potrzebuje konkretnej informacji w konkretnym momencie, zwykle stojąc przy urządzeniu, a nie przeglądając katalog wieczorem przy biurku.

Wcześniejsza wersja portalu działała na WordPressie i sprowadzała się do listy produktów z podpiętymi plikami do pobrania. Nie było wyszukiwania po treści dokumentów, nie było czytelnego wersjonowania, nie było asystenta ani zapisów na szkolenia. Użytkownik, który nie znał dokładnej nazwy produktu, musiał przewijać listę.

Nie był to błąd wykonania, tylko konsekwencja narzędzia. WordPress jest systemem do publikowania treści i w tej roli sprawdza się dobrze. Portal dokumentacji technicznej to jednak inna klasa aplikacji: wymaga indeksowania zawartości plików, kontroli rewizji, równoległych wersji językowych powiązanych z jednym produktem i kont zakładanych po stronie producenta. Realizacja tego na CMS-ie oznacza budowanie łańcucha wtyczek, z których każda odpowiada za wycinek problemu, żadna nie zna kontekstu pozostałych, a całość trzeba aktualizować i modlić się o zgodność. Przy tej skali szybciej i taniej jest napisać aplikację niż utrzymywać obejście.

02. Rozwiązanie

Zbudowaliśmy portal, w którym cała dokumentacja produktowa jest w jednym miejscu, zawsze w aktualnej wersji, dostępna po zalogowaniu.

Konta zakłada administrator po stronie producenta, więc dostęp mają wyłącznie partnerzy i instalatorzy, a nie przypadkowi odwiedzający. Każdy produkt ma swoją kartę, na której zebrane są wszystkie powiązane z nim pliki, uporządkowane według typu dokumentu, wersji i języka.

Nad tym działają dwa mechanizmy wyszukiwania. Wyszukiwarka przeszukuje nie tylko nazwy plików, ale też ich treść, łącznie z zawartością dokumentów PDF. Asystent AI odpowiada na pytania zadane zwykłym językiem, opierając odpowiedź na dokumentacji konkretnego produktu.

Portal obsługuje również zapisy na szkolenia produktowe, dzięki czemu partner ma w jednym miejscu i wiedzę, i możliwość jej pogłębienia.

03. Jak to działa

Karta produktu jako punkt odniesienia

Każdy produkt ma jedną kartę, na której znajdują się wszystkie dotyczące go dokumenty. Wersjonowanie jest widoczne wprost: użytkownik wie, którą rewizję pobiera i czy istnieje nowsza. Producent, publikując aktualizację, nie musi nikogo o niej informować, bo partner sięga po dokument do źródła, a nie do kopii sprzed roku.

Wszystkie materiały prowadzone są równolegle w wersji polskiej, angielskiej i niemieckiej. Zmiana języka nie przerzuca użytkownika na stronę główną, tylko pokazuje ten sam dokument w wybranej wersji, jeśli jest dostępna.

Wyszukiwanie po treści dokumentów

Wyszukiwarka indeksuje zawartość plików, nie tylko ich metadane. Zapytanie o oznaczenie złącza, kod błędu czy nazwę parametru znajduje dokument nawet wtedy, gdy fraza występuje wyłącznie na dwudziestej stronie instrukcji. Wyniki obejmują zarówno produkty, jak i pojedyncze dokumenty, z podpowiedziami przy literówkach i odmianie.

Asystent odpowiadający z dokumentacji

Asystent przyjmuje pytanie zadane tak, jak instalator sformułowałby je przez telefon do wsparcia technicznego. W odpowiedzi wskazuje właściwą instrukcję albo wprost opisuje, co należy zrobić w opisanej sytuacji, opierając się na treści dokumentów instalacyjnych.

Kluczowe jest ograniczenie źródła. Asystent odpowiada wyłącznie na podstawie dokumentacji producenta, a nie ogólnej wiedzy modelu językowego, i wskazuje dokument, z którego pochodzi odpowiedź. Instalator może ją zweryfikować, zanim podejmie decyzję przy urządzeniu. Przy pytaniu wykraczającym poza dokumentację asystent to sygnalizuje, zamiast zgadywać.

Szkolenia

Partnerzy zapisują się na szkolenia produktowe bezpośrednio z portalu, w tym samym miejscu, w którym korzystają z dokumentacji.

Statystyki wykorzystania

Portal rejestruje, które pliki są pobierane, jak często i przez kogo, oraz które produkty cieszą się największym zainteresowaniem. Producent widzi też, o co najczęściej pytany jest asystent.

Te dane mają zastosowanie wykraczające poza raportowanie. Dokument pobierany wielokrotnie przez tego samego instalatora zwykle oznacza, że informacja jest w nim trudna do znalezienia. Powtarzające się pytanie do asystenta wskazuje lukę w dokumentacji. Wykorzystanie portalu staje się źródłem informacji zwrotnej o jakości samych materiałów, a przy okazji o tym, które produkty wymagają wsparcia sprzedażowego, a które szkoleniowego.

Wykorzystane technologie

• Aplikacja: Next.js, TypeScript, React
• Baza danych: PostgreSQL
• Wyszukiwanie: Meilisearch, indeksowanie treści plików PDF
• Asystent: model językowy z wyszukiwaniem semantycznym po dokumentacji, odpowiedzi ograniczone do materiałów producenta
• Dostęp: konta zakładane przez administratora, uwierzytelnianie sesyjne
• Wdrożenie: Docker, nginx

04. Rezultaty

Aktualna dokumentacja przestała być czymś, o co trzeba poprosić. Partner znajduje ją sam, o dowolnej porze, bez pośrednictwa działu wsparcia i bez ryzyka, że pracuje na nieaktualnej rewizji.

Pytania, na które odpowiedź jest w instrukcji, przestały trafiać do ludzi. Wsparcie techniczne zajmuje się sytuacjami nietypowymi, a nie odsyłaniem do rozdziału dokumentu.

Trzy wersje językowe obsługiwane są tym samym nakładem pracy co jedna. Publikacja aktualizacji sprowadza się do wgrania pliku na kartę produktu.

Producent przestał pracować w ciemno. Wie, po jakie dokumenty sięgają instalatorzy, które produkty generują najwięcej pytań i gdzie dokumentacja wymaga poprawy. Wcześniejsza wersja portalu nie dostarczała żadnej z tych informacji.