Jak zespół ds. dokumentacji naprawił właściwe strony, pytając o to na samej stronie

Projekt open-source ma dobrą dokumentację i prawdziwy problem: przewodnik instalacji zawiera subtelny błąd. Jeden z kroków zmienił się dwie wersje temu, a teraz nowi użytkownicy utykają w tym samym punkcie. Ludzie to zauważają — pojawiają się narzekania w mediach społecznościowych i kilka zdezorientowanych pytań na czacie społeczności — ale opiekunowie projektu nie mogą nic z tym zrobić, ponieważ żadna ze skarg nie mówi, **której strony** dotyczy. 'Wasza dokumentacja jest nieaktualna' to odczucie, a nie zgłoszenie błędu. Więc błędny krok tkwi tam miesiącami, po cichu zniechęcając każdego nowego użytkownika, który próbuje zacząć. Dokumentacja żyje lub umiera w tym cyklu: czytelnik trafia na mylący lub błędny fragment, mówi opiekunom dokładnie gdzie to jest, a opiekunowie to naprawiają. Przerwij element 'dokładnie gdzie', a cały cykl utknie w martwym punkcie. ## Problem: feedback bez lokalizacji to szum Czytelnicy są chętni do pomocy. Z radością powiedzą Ci, że strona jest myląca. Czego jednak nie zrobią, to archeologii niezbędnej, by tę pomoc dało się wykorzystać w praktyce — skopiowania URL, znalezienia odpowiedniego kanału kontaktu, opisania problemu oraz odnotowania, której sekcji i wersji dotyczy. To wiele kroków dla kogoś, kto próbuje nauczyć się Twojego narzędzia, a nie przeprowadzać audyt Twojej dokumentacji. Dlatego feedback, który dociera, jest pozbawiony jedynej rzeczy, która czyni go użytecznym: lokalizacji. Opiekun czytający 'dokumentacja API jest błędna' ma setki stron i nie ma pojęcia, gdzie szukać. Zgłoszenie na GitHubie pomaga, ale wymaga od przypadkowego czytelnika posiadania konta, zrozumienia szablonu zgłoszenia i całkowitej zmiany kontekstu poza dokumentację — to tarcie, które odfiltrowuje większość przelotnego feedbacku, a to właśnie ten feedback wyłapuje małe błędy o dużym wpływie. Rezultatem jest dziwna nierównowaga: wielu czytelników zauważa problemy, ale prawie żadne nie są zgłaszane w formie, którą możesz naprawić. ## Rozwiązanie: link 'Zgłoś problem' na każdej stronie Umieść mały link **Zgłoś problem z tą stroną** w stopce każdej strony dokumentacji. Jest to link `mailto:`, a jego trik polega na tym, że wstępnie wypełnia obecną ścieżkę strony w temacie i treści wiadomości. Czytelnik klika, jego e-mail otwiera się z już przechwyconą lokalizacją, a jedyne co musi dodać, to co było nie tak. Ponieważ dokumentacja jest zazwyczaj budowana z szablonu lub generatora stron statycznych, możesz automatycznie wstrzyknąć ścieżkę. W stronie opartej na szablonie wrzuć zmienną strony prosto do linku: ```html <a href="mailto:[email protected]?subject=Docs issue: {{page.path}}&body=Page: {{page.path}}%0A%0AWhat is wrong or confusing:%0AWhat would make it clearer:"> Zgłoś problem z tą stroną </a> ``` Lub ustaw go za pomocą linijki skryptu, aby działał na dowolnej stronie bez szablonów: ```html <a id="docs-issue" href="#">Zgłoś problem z tą stroną</a> <script> const a = document.getElementById('docs-issue'); const path = location.pathname; const body = 'Page: ' + path + '\n\nWhat is wrong or confusing:\nWhat would make it clearer:'; a.href = 'mailto:[email protected]' + '?subject=' + encodeURIComponent('Docs issue: ' + path) + '&body=' + encodeURIComponent(body); </script> ``` Generator na tej stronie tworzy zakodowany link; skrypt podmienia tylko ścieżkę na żywo. Teraz każde zgłoszenie podaje w temacie dokładną stronę, a opiekun może przeskoczyć prosto do pliku źródłowego. ## Dlaczego na stronie jest lepsze do tego niż issue tracker Issue tracker to odpowiednie miejsce dla poprawek, ale słabe drzwi wejściowe dla feedbacku. Wymaga konta, zmiany kontekstu i znajomości Twojego procesu — barier, które odstraszają przypadkowego czytelnika, który właśnie zauważył literówkę w przykładowym kodzie. Link `mailto:` spotyka czytelników tam, gdzie faktycznie pojawia się zamieszanie: na stronie, jednym kliknięciem, bez konta. Wychwytuje długi ogon małych korekt, które nigdy nie przetrwałyby podróży do trackera. Oba rozwiązania dobrze ze sobą współpracują. Zgłoszenia docierają e-mailem, wstępnie otagowane stroną; opiekun je segreguje i otwiera zgłoszenia w trackerze tylko dla tych, które warto śledzić. Otrzymujesz niskie tarcie e-maila na froncie i rygor trackera na zapleczu. ## Konfiguracja 1. Wybierz skrzynkę odbiorczą dla dokumentacji, taką jak `docs@`, którą obserwują opiekunowie. 2. W generatorze ustaw odbiorcę, temat 'Docs issue: [ścieżka strony]' oraz treść, która pyta, co jest nie tak i co by pomogło. 3. Dodaj link do stopki szablonu swojej strony, wstrzykując ścieżkę za pomocą zmiennej strony Twojego generatora lub małego skryptu powyżej. 4. Kieruj przychodzącą pocztę za pomocą tagu tematu 'Docs issue:', aby zgłoszenia trafiały w jedno miejsce. 5. Zamknij cykl: kiedy poprawisz zgłoszoną stronę, jednozdaniowa odpowiedź do czytelnika zmienia zgłoszenie błędu w dobrą wolę. ## Co to oszczędza Pierwszą oszczędnością jest **czas opiekuna poświęcony na lokalizowanie problemów**. Gdy każde zgłoszenie podaje stronę, pomijasz pracę detektywistyczną i przechodzisz od razu do poprawki. Zgłoszenie, które kiedyś było bezużytecznym 'coś jest gdzieś nie tak', staje się dwuminutową edycją. Drugą jest **mniejsza liczba utkniętych użytkowników**. Błędy w dokumentacji się kumulują: błędny krok instalacji nie zawodzi tylko raz, zawodzi dla każdego nowicjusza, dopóki ktoś go nie naprawi. Skrócenie czasu od 'czytelnik zauważa' do 'opiekun wie dokładnie gdzie' oznacza, że każdy zły fragment odstrasza znacznie mniej osób. Dla narzędzia, które rośnie dzięki adopcji, odblokowanie nowicjuszy oznacza wzrost. Trzecią jest **objętość i szczerość feedbacku**. Ponieważ zgłoszenie wymaga jednego kliknięcia i żadnego konta, robi to więcej czytelników — w tym ci, którzy nigdy nie otworzyliby zgłoszenia w trackerze. Dowiadujesz się o małych, kłopotliwych błędach, które nadszarpują zaufanie, i dowiadujesz się o nich wtedy, kiedy wciąż mają znaczenie. ## Jak sprawić, by było jeszcze lepiej - Automatycznie wypełnij **wersję dokumentacji lub commit** obok ścieżki, abyś mógł stwierdzić, czy zgłoszenie poprzedza niedawne przepisanie treści. - Dodaj link do **stron 404** w swojej dokumentacji, gdzie brakująca strona sama w sobie jest użytecznym sygnałem. - Utrzymuj adres **zaciemniony**, aby boty nie zbierały go z tysięcy publicznych stron. - Zaoferuj widoczną alternatywę dla czytelników bez domyślnej aplikacji pocztowej, na przykład zwykły adres lub link do trackera. ## Kluczowe wnioski - Feedback dotyczący dokumentacji bez lokalizacji to szum; czytelnicy rzadko wykonują pracę, aby ją dołączyć. - Link `mailto:` 'Zgłoś problem' na każdej stronie wstępnie wypełnia dokładną ścieżkę, więc każde zgłoszenie jest wykonalne. - E-mail na stronie wychwytuje przypadkowe korekty, które tracker odfiltrowuje, a następnie zasila tracker pod kątem prawdziwych poprawek. - Oszczędza czas opiekunów, szybciej odblokowuje nowicjuszy i ujawnia małe błędy, które po cichu kosztują zaufanie. Zbuduj swój własny link do feedbacku dokumentacji w [generatorze](/#generator), lub skopiuj poniższą konfigurację.